Lumen CLI
lumen
Lumen shows git diffs and GitHub pull requests in the terminal and, if you want, writes commit messages and explains changes through the model you pick
- 2,899 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- In model mode the text of your changes and questions go to the selected provider
- `lumen operate` runs a generated git command after confirmation, and the command can change history
- The provider key is stored in `lumen.config.json` as plain text
Install
- Works in
Manual install
brew install jnsahaj/lumen/lumenHomebrew on macOS and Linux. Requires git.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- In model mode the text of your changes and questions go to the selected provider
- `lumen operate` runs a generated git command after confirmation, and the command can change history
- The provider key is stored in `lumen.config.json` as plain text
This is third-party code. Review the repository files before installing.
What it does
Lumen is a Rust program shipped as a single executable. `lumen diff` opens a side-by-side change viewer in the terminal with tree-sitter syntax highlighting. The source can be uncommitted changes, a commit, a branch range, a GitHub pull request by number or link, or a Jujutsu repository. `--stacked` steps through commits one at a time, and `--watch` refreshes the view when files change. You attach comments to a selection, a hunk or a whole file with the mouse or the `i` key. For agent work, comments go out on the `s` key: Lumen closes the window and prints them as text to standard output, so Claude Code or Codex receives the notes as its next prompt. You run `!lumen diff` inside the agent, and no separate plugin is needed. An optional part connects a language model. `lumen draft` writes a commit message from the staged changes, `lumen explain` describes changes or answers your question about them, and `lumen operate` turns a plain-language request into a git command and asks for confirmation before running it. The provider, key and model are set with `lumen configure`, flags or environment variables.
Who it is for. For developers who review agent edits and pull requests without leaving the terminal and want commit messages from a model of their choice, including a local one.
Good fit when
- An agent finished a turn and you want to go through its edits line by line and send notes back as the next prompt with `!lumen diff` and the `s` key
- A GitHub pull request is easier to read in the terminal with `lumen diff --pr 123` than in a browser
- Commit messages should follow conventional commits: `lumen draft` takes the types from the settings and accepts extra context via `--context`
- A series of commits has to be reviewed one by one with files marked as viewed, which is what `--stacked` does
- Code must not go to outside services: Ollama in the provider list runs locally and needs no key
Not a fit when
- You want to review changes in a browser in the familiar GitHub layout: difit does that, while Lumen works in the terminal only
- You need an agent that edits code and commits on its own: Lumen shows and describes changes but writes no code
- You need a replacement for `git` on systems without it: git is a hard requirement and the tool does not work without it
- Installing Rust programs is not allowed: delivery goes through Homebrew or `cargo install`, and the source lists no packages for other managers
Example request
Open the changes you just made in Lumen, I will leave notes and you fix themLimitations
- The viewer works without a model. The `draft`, `explain` and `operate` commands need a provider, and every provider except Ollama needs a key.
- In model mode the text of your changes goes to the selected provider. The key can sit in `lumen.config.json` in plain text, so keep that file out of the repository.
- `lumen operate` runs the generated git command after you answer `y`. The command may rewrite history, so read it before confirming.
- `lumen explain --list` needs fzf, and formatted output needs mdcat. Both are optional.
- Default model names in the provider table follow provider releases, so check the current list with the provider.
How to disable. Lumen does not hook into the agent: it does nothing until you run `lumen`. Remove it with the manager you used, `brew uninstall lumen` or `cargo uninstall lumen`, and delete `~/.config/lumen/lumen.config.json` with the provider key if you want.
FAQ
Do I need a key just to view changes?
No. `lumen diff` works without a provider, and only `draft`, `explain` and `operate` need a key. Ollama needs none either.
How do I send notes back to the agent?
Run `!lumen diff` in Claude Code or Codex, leave comments with the `i` key, press `s` and confirm with Enter. Lumen prints the notes as text to standard output and the agent receives them as the next prompt. The `y` key copies the same text to the clipboard.
Which models can I connect?
The provider table lists OpenAI (the default), Claude, Gemini, Groq, DeepSeek, xAI, OpenCode Zen, Ollama, OpenRouter and Vercel AI Gateway. Pick one with the `-p` flag, the `LUMEN_AI_PROVIDER` variable or `lumen configure`.
Where does Lumen take settings from when they are set in several places?
Command-line arguments win, then the file passed with `--config`, then `lumen.config.json` in the project root and finally the global file in `~/.config/lumen`. The theme follows a different order: flag, file, the `LUMEN_THEME` variable, auto-detection.
Does Lumen work with anything besides git?
Yes, the sources have separate modules for git and Jujutsu, and the version control system is detected automatically. GitHub pull requests open by number, by link, or with `--detect-pr` for the current branch.
Discussion
No questions or reviews yet.
Related
CLI toolsA local gate in front of git push: the branch goes through review, tests, docs and lint in a separate worktree before it reaches the remote with a PR
A Git merge driver and MCP server that compares functions and classes and removes false conflicts from parallel agent edits
A Rust code-quality sensor that scores a project before and after an agent session, installable as a Claude Code plugin or MCP server
A native macOS terminal built on Ghostty with vertical tabs and notifications when an agent needs your input
A git worktree CLI built for running Claude Code and Codex in parallel: the wt command, a plugin, and automation hooks
OpenTelemetry-based CLI tracing for Claude Code, Cursor and Codex sessions, showing what the agent actually did and what it cost
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| Lumen (this entry) | no | 2,899 | |
| difit | no | 3,273 | opens the diff in a browser in the GitHub layout and copies comments as a prompt; Lumen works in the terminal and writes commit messages |
| open-code-review | no | 47,953 | an agent reads the diff and writes line comments itself; in Lumen you leave the comments |
README in short
The repository holds the Rust sources, `Cargo.toml`, a Nix configuration and a release script. The documentation covers installation, the diff viewer commands with a key list and a table of themes, the model commands with examples, a provider table with default models and a section on coding agent integration. It ends with the settings file format and the precedence order of sources.