lumen

Lumen allows you to add review comments at three levels of granularity:

• Selection: Select text with the mouse and press i to annotate the range.
• Hunk: Focus a hunk with { or } and press i to annotate the hunk.
• File: Press i with no selection or hunk focus to annotate the entire file.

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

Lumen applies configuration options based on a specific hierarchy. If a setting is defined in multiple places, the higher priority source wins. The order from highest to lowest priority is:

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

This allows you to set global defaults via environment variables and override them on a per-project basis with a config file, or even for a single command execution using CLI flags.

# 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

Lumen can be used as a review surface for coding agents (like Claude Code or Codex). The agent can shell-escape to lumen, allow you to annotate the diff, and then receive your annotations back via stdout.

Workflow:

1. Agent finishes turn.
2. Agent runs !lumen diff (or similar shell command).
3. User annotates the diff using i.
4. User presses s to confirm.
5. Lumen exits and writes formatted annotations to stdout.
6. Agent receives the annotations and applies fixes.

agent finishes turn → !lumen diff → annotate → press `s`
→ stdout returns to the agent → agent fixes your notes

To use AI helpers (commit messages, explanations, etc.), you must configure a provider and API key. Run the interactive setup command:

lumen configure

Settings are saved to ~/.config/lumen/lumen.config.json.

You can install lumen using Homebrew (macOS/Linux) or Cargo (Rust package manager).

Prerequisites

• git must be installed on your system.
• fzf (optional): Required for the lumen explain --list command.
• mdcat (optional): Required for pretty output formatting.

# Using Homebrew
brew install jnsahaj/lumen/lumen

# Using Cargo
cargo install lumen

The Selection struct tracks how a user has selected text within a diff panel. It supports two primary modes:

• SelectionMode::Character: Selecting specific characters/columns.
• SelectionMode::Line: Selecting entire lines.

Key properties:

• panel: The DiffPanelFocus where the selection resides (Old or New).
• anchor: The starting CursorPosition.
• head: The current end of the selection.
• mode: The SelectionMode used.

Useful methods:

• .is_active(): Returns true if a selection is currently active.
• .contains(line, column): Checks if a specific coordinate is within the selection.
• .is_line_fully_selected(line): Checks if an entire line is included in the selection.
• .normalized_range(): Returns the selection as a (start, end) tuple where start <= end.

FileHighlighter is a high-level abstraction for syntax highlighting that handles the complexity of mapping byte-offset highlights from tree-sitter to human-readable line numbers.

It works by:

1. Loading the appropriate LanguageConfig based on the file extension.
2. Running the tree-sitter highlighter over the entire content.
3. Mapping the resulting byte offsets to 1-based line numbers.
4. Storing these in a HashMap where the key is the line number and the value is a list of text segments and their associated highlight indices.

The Modal struct is used to present various interactive overlays within the Lumen diff view. Depending on the ModalContent variant, the modal can display information, request confirmation, pick files, show keybindings, manage annotations, or perform a global search.

Each modal type has specific constructor methods to initialize its content and state.

The JjBackend implementation includes logic to detect common Git-style references and suggest their Jujutsu equivalents to prevent errors.