A fast terminal diff viewer and code review TUI, written in Rust.

Review git diff, commits, branches, or GitHub PRs side-by-side without leaving your terminal. Ships as a single static Rust binary and stays snappy on multi-thousand-line diffs.

• Side-by-side diff viewer with tree-sitter syntax highlighting
• Review GitHub Pull Requests with lumen diff --pr 123
• Annotate selections, hunks, or whole files
• Watch mode and stacked-commit review
• Optional AI commit messages and change explanations (10+ providers)
• Works with Git and Jujutsu (jj)

• Getting Started
  • Prerequisites
  • Installation
• Usage
  • Visual Diff Viewer
• AI Features
  • Configuration
  • Generate Commit Messages
  • Generate Git Commands
  • Explain Changes
  • Tips & Tricks
  • AI Providers
• Advanced Configuration
  • Configuration File
  • Configuration Precedence

Before you begin, ensure you have:

1. git installed on your system
2. fzf (optional) - Required for lumen explain --list command
3. mdcat (optional) - Required for pretty output formatting

brew install jnsahaj/lumen/lumen

cargo install lumen

Launch an interactive side-by-side diff viewer in your terminal:

# View uncommitted changes
lumen diff

# View changes for a specific commit
lumen diff HEAD~1

# View changes between branches
lumen diff main..feature/A

# View changes in a GitHub Pull Request
lumen diff --pr 123 # (--pr is optional)
lumen diff https://github.com/owner/repo/pull/123

# Filter to specific files
lumen diff --file src/main.rs --file src/lib.rs

# Watch mode - auto-refresh on file changes
lumen diff --watch

# Stacked mode - review commits one by one
lumen diff main..feature --stacked

# Jump to a specific file on open
lumen diff --focus src/main.rs

Review a range of commits one at a time with --stacked:

lumen diff main..feature --stacked
lumen diff HEAD~5..HEAD --stacked

This displays each commit individually, letting you navigate through them:

• ctrl+h / ctrl+l: Previous / next commit
• Click the ‹ / › arrows in the header

The header shows the current commit position, SHA, and message. Viewed files are tracked per commit, so your progress is preserved when navigating.

When viewing a PR, you can mark files as viewed (syncs with GitHub) using the space keybinding.

Customize the diff viewer colors with preset themes:

# Using CLI flag
lumen diff --theme dracula

# Using environment variable
LUMEN_THEME=catppuccin-mocha lumen diff

# Or set permanently in config file (~/.config/lumen/lumen.config.json)
{
  "theme": "dracula"
}

Available themes:

Priority: CLI flag > config file > LUMEN_THEME env var > OS auto-detect.

Selection: Click-drag in the content area for character-level selection, or on line numbers for line-level selection. Selected text can be copied or annotated.

Annotations: Add review comments at three levels of granularity:

• Selection — select lines with mouse, press i to annotate the selected range
• Hunk — focus a hunk with {/}, press i to annotate the hunk
• File — press i with no selection or hunk focus to annotate the whole file

Annotated lines display a ▍ gutter indicator. Use I to view, edit, delete, copy, or export all annotations.

• j/k or arrow keys: Navigate
• {/}: Jump between hunks
• tab: Toggle sidebar
• space: Mark file as viewed
• e: Open file in editor
• y: Copy selection (or filename)
• i: Annotate selection / hunk / file
• I: View all annotations
• ctrl+h/l: Previous/next commit (stacked mode)
• ?: Show all keybindings

Lumen also bundles optional AI helpers for commit messages, explanations, and natural-language git commands. These require configuring an AI provider — the diff viewer above does not.

Run lumen configure for interactive setup (provider, API key, model). Settings are saved to ~/.config/lumen/lumen.config.json.

Create meaningful commit messages for your staged changes:

# Basic usage - generates a commit message based on staged changes
lumen draft
# Output: "feat(button.tsx): Update button color to blue"

# Add context for more meaningful messages
lumen draft --context "match brand guidelines"
# Output: "feat(button.tsx): Update button color to align with brand identity guidelines"

Ask Lumen to generate Git commands based on a natural language query:

lumen operate "squash the last 3 commits into 1 with the message 'squashed commit'"
# Output: git reset --soft HEAD~3 && git commit -m "squashed commit" [y/N]

The command will display an explanation of what the generated command does, show any warnings for potentially dangerous operations, and prompt for confirmation before execution.

Understand what changed and why:

# Working directory or staged changes
lumen explain
lumen explain --staged

# Specific commits or ranges
lumen explain HEAD
lumen explain HEAD~3..HEAD
lumen explain main..feature/A

# Ask specific questions
lumen explain --query "What's the performance impact of these changes?"

# Interactive commit selection (requires: fzf)
lumen explain --list

# Copy commit message to clipboard (macOS / Linux)
lumen draft | pbcopy
lumen draft | xclip -selection c

# Directly commit using the generated message
lumen draft | git commit -F -

lazygit integration is available — see the user config docs for binding lumen draft to a custom command.

Configure your preferred AI provider:

# Using CLI arguments
lumen -p openai -k "your-api-key" -m "gpt-5-mini" draft

# Using environment variables
export LUMEN_AI_PROVIDER="openai"
export LUMEN_API_KEY="your-api-key"
export LUMEN_AI_MODEL="gpt-5-mini"

Lumen supports configuration through a JSON file. You can place the configuration file in one of the following locations:

1. Project Root: Create a lumen.config.json file in your project's root directory.
2. Custom Path: Specify a custom path using the --config CLI option.
3. Global Configuration (Optional): Place a lumen.config.json file in your system's default configuration directory:
   • Linux/macOS: ~/.config/lumen/lumen.config.json
   • Windows: %USERPROFILE%\.config\lumen\lumen.config.json

Lumen will load configurations in the following order of priority:

1. CLI arguments (highest priority)
2. Configuration file specified by --config
3. Project root lumen.config.json
4. Global configuration file (lowest priority)

{
  "provider": "openai",
  "model": "gpt-5-mini",
  "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "theme": "catppuccin-mocha",
  "draft": {
    "commit_types": {
      "docs": "Documentation only changes",
      "style": "Changes that do not affect the meaning of the code",
      "refactor": "A code change that neither fixes a bug nor adds a feature",
      "perf": "A code change that improves performance",
      "test": "Adding missing tests or correcting existing tests",
      "build": "Changes that affect the build system or external dependencies",
      "ci": "Changes to our CI configuration files and scripts",
      "chore": "Other changes that don't modify src or test files",
      "revert": "Reverts a previous commit",
      "feat": "A new feature",
      "fix": "A bug fix"
    }
  }
}

Options are applied in the following order (highest to lowest priority):

1. CLI Flags
2. Configuration File
3. Environment Variables
4. Default options

Example: Using different providers for different projects:

# Set global defaults in .zshrc/.bashrc
export LUMEN_AI_PROVIDER="openai"
export LUMEN_AI_MODEL="gpt-5-mini"
export LUMEN_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

# Override per project using config file
{
  "provider": "ollama",
  "model": "llama3.2"
}

# Or override using CLI flags
lumen -p "ollama" -m "llama3.2" draft

Made with contrib.rocks.

Contributions are welcome! Please feel free to submit a Pull Request.