# jnsahaj/lumen: a terminal diff viewer with optional AI commit messages

> Lumen is a Rust TUI for reviewing git diffs, commits, branches and GitHub pull requests side by side, with an optional AI layer for commit messages and change explanations. The viewer works without any provider; the AI helpers do not.

**jnsahaj/lumen** — Beautiful git diff viewer, generate commits with AI, get summary of changes, all from the CLI

- Repository: https://github.com/jnsahaj/lumen
- Stars: 2,877 · Forks: 151
- Language: Rust
- License: MIT
- Published: 2026-09-09 · Updated: 2026-09-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/jnsahaj-lumen

## What lumen replaces, and for whom

Git's own pager shows a diff as a single column of plus and minus lines. Reading a large refactor that way means scrolling back and forth to match a removed line with its replacement. Lumen draws the same diff side by side in a terminal, with syntax highlighting via tree-sitter, and adds review affordances on top: selecting lines, annotating a selection, a hunk or a whole file, and marking files as viewed. The README describes the target user directly: someone who wants to "review git diff, commits, branches, or GitHub PRs side-by-side without leaving your terminal." That is a narrower audience than a general git GUI, and the design choices follow from it. There is no mouse-free-only workflow and no server component. The binary is Rust, distributed as a single static executable, which matters for people who work over SSH or in containers where installing a GUI toolkit is not an option. The AI features are explicitly optional. The README states that the diff viewer does not require configuring a provider, and that only the commit-message, explanation and natural-language git command helpers do.

## How the diff viewer is put together

The dependency list in Cargo.toml is the clearest description of the architecture. ratatui and crossterm provide the terminal UI and input handling, so the whole interface is drawn as cells rather than rendered by a graphics stack. similar, with the inline and unicode features enabled, computes the diff, which is why the viewer can show character-level inline changes inside a changed line rather than only whole-line additions and deletions. tree-sitter plus tree-sitter-highlight and a set of per-language grammar crates handle colouring; the listed grammars cover TypeScript, JavaScript, Rust, JSON, Python, Go, CSS, HTML, TOML, Bash, Markdown, C#, Ruby, Elixir, Java, Zig, C and C++. That list is fixed at build time, so a language outside it falls back to unhighlighted text. git2 with vendored libgit2 and vendored OpenSSL is used for repository access, and jj-lib appears in the dependency list, which is how Jujutsu support is wired in. notify and notify-debouncer-mini back the watch mode that refreshes the view when files change. arboard handles clipboard writes, with the wayland-data-control feature enabled for Wayland sessions. The AI path is separate: genai abstracts the model providers, reqwest does the HTTP, and the README says more than ten providers are supported. Nothing in the dependency list suggests a background daemon or a persistent cache, so each invocation reads the repository and draws.

## Installing lumen and reviewing your first diff

The README gives two install paths. On macOS and Linux there is a Homebrew tap, and there is a crates.io package for anyone with a Rust toolchain. Both install the same binary. The prerequisites section lists git as required, and marks fzf and mdcat as optional, with fzf needed only for the explain --list command and mdcat only for pretty output formatting.

```bash
brew install jnsahaj/lumen/lumen
```

Alternatively, if cargo is already on the machine:

```bash
cargo install lumen
```

After that, running lumen diff with no arguments opens the interactive side-by-side viewer for uncommitted changes. The README's usage section lists the variants: lumen diff HEAD~1 for a single commit, lumen diff main..feature/A for a range, lumen diff --pr 123 or a full pull request URL for a GitHub PR, and lumen diff --detect-pr to open the PR attached to the current branch. --file narrows the view to named paths, --focus jumps to one file on open, --watch refreshes on file changes, and --stacked walks a commit range one commit at a time. Inside the viewer, j and k or the arrow keys navigate, { and } jump between hunks, space marks a file as viewed (which the README says syncs with GitHub when you are viewing a PR), e opens the file in your editor, y copies the selection or filename, and ? lists every keybinding.

```bash
lumen diff main..feature --stacked
```

In stacked mode the header shows the current commit position, its SHA and message, and ctrl+h and ctrl+l move between commits. The README notes that viewed files are tracked per commit, so progress survives navigation. If you want a different colour scheme, the theme can be set in three places, and the README states the precedence explicitly: CLI flag, then config file, then the LUMEN_THEME environment variable, then OS auto-detection.

```bash
LUMEN_THEME=catppuccin-mocha lumen diff
```

The available theme values include dark, light, catppuccin-mocha, catppuccin-latte, dracula, nord, one-dark, gruvbox-dark, gruvbox-light, solarized-dark, solarized-light, flexoki-dark and flexoki-light.

## Annotations, and where the AI layer actually sits

Annotations are the feature that distinguishes lumen from a plain pager. Pressing i with a mouse selection annotates that range, pressing it with a hunk focused (via { and }) annotates the hunk, and pressing it with neither annotates the whole file. Annotated lines get a gutter marker, and I opens a view where annotations can be edited, deleted, copied or exported. That is a review workflow that stays local: the README does not describe pushing annotations anywhere except the file-viewed state on a GitHub PR. The AI side is deliberately separate. lumen configure runs an interactive setup for provider, API key and model, writing to ~/.config/lumen/lumen.config.json. lumen draft generates a commit message from staged changes, and accepts a --context string to steer it; the README's example shows the message changing from a plain description of a button colour update to one that mentions brand guidelines when that context is supplied. There is also a command for generating git commands from natural language and an explain command for change summaries. The important boundary is that these features send diff content to a third-party model provider. Anyone reviewing proprietary code should treat the AI commands as an egress point and the viewer as local-only, because that is how the README splits them.

## Limits: language coverage, network reach and PR assumptions

The most concrete limitation is the grammar list. Highlighting comes from tree-sitter crates compiled into the binary, and the Cargo.toml enumerates them. A repository written mostly in a language outside that set will render as plain text, which removes much of the reason to use lumen over git diff. A second constraint is the GitHub PR path. lumen diff --pr 123 and the URL form assume GitHub, and the file-viewed sync is described as a GitHub behaviour; the README does not document equivalent support for GitLab, Bitbucket or a self-hosted forge. Teams on those platforms get the local viewer and lose the PR integration. Third, the AI commands require network access and a configured provider, so they are unusable in an air-gapped environment, and the README does not document a local-model path even though genai is the abstraction layer. Fourth, the viewer is mouse-oriented in places: selection is described as click-drag in the content area or on line numbers, and annotations are attached to selections or hunks. Terminal mouse reporting is not universal, and the README does not document a keyboard-only route to character-level selection. Finally, watch mode depends on filesystem notifications through notify, and the README does not describe behaviour on network filesystems where those events are unreliable.

## How it differs from delta and from a web review tool

The nearest comparison is delta, which also improves git diff output in a terminal. The approaches differ in kind. Delta is configured as a git pager and produces improved static output: you scroll, and the diff is text. Lumen takes over the terminal and runs an interactive TUI with a sidebar, hunk navigation, selection, annotations and a watch mode that redraws on file changes. If your workflow is piping diffs into a pager and reading, delta fits without changing how you invoke git. If your workflow is reviewing, marking progress and leaving comments for yourself or a PR, lumen provides the state that a pager cannot hold. The second comparison is a web review surface such as a GitHub pull request page. Lumen's PR mode reads the PR into the terminal and syncs the viewed state back, which is useful when the diff is large or the connection is slow, but the README does not describe commenting on the PR from lumen. Annotations are local, and the README documents export of annotations, not submission to GitHub. So lumen is a replacement for reading and triaging a diff, not for the discussion that happens around it.

## Licence and the cost of keeping up

Lumen is MIT licensed, per both the LICENSE file at the repository root and the license field in Cargo.toml. That is permissive: it allows use, modification and redistribution provided the copyright notice and permission notice are retained, and it comes with no warranty. For a CLI tool that a team installs on developer machines, the practical implication is that internal forks and repackaging are allowed; it does not oblige you to publish changes. This is a description of the licence text, not legal advice, and anyone embedding lumen in a distributed product should read the LICENSE file themselves. On upgrade cost, the repository is not archived and the last push was on 2026-07-16, with v2.32.0 released the same day and v2.31.0 the day before. Release cadence is therefore not something you can infer from a single pair of dates, and the README does not document a stability or deprecation policy. Two upgrade risks are visible from the file layout. The tree-sitter grammar dependencies are pinned to specific minor versions, so adding a language means touching Cargo.toml and rebuilding rather than dropping in a plugin. And configuration lives in ~/.config/lumen/lumen.config.json with a documented precedence order, so a config key that changes meaning between versions will silently alter behaviour for anyone who set it in that file rather than passing a flag. Pin a version in your install script if you need reproducibility, and read the release notes before moving.

## Conclusion

Adopt lumen if you review diffs, stacked commits or GitHub PRs in a terminal and want annotations and syntax highlighting without leaving the shell, and only configure a provider if you actually want the draft and explain commands. Skip it if you need a GUI, a web review surface, or if a single static binary conflicts with your distribution's packaging rules; lumen ships on crates.io and through a Homebrew tap rather than in distro repositories. Verify three things first: that your terminal handles mouse selection and clipboard as the README describes, that your chosen AI provider is reachable from the machine (the AI commands are the only part that needs network access), and that tree-sitter highlighting covers your language, since the Cargo.toml lists a fixed grammar set that does not include every language.

## FAQ

### What exactly is lumen?

It is a Rust terminal application that shows git diffs side by side with tree-sitter syntax highlighting, and adds annotations, watch mode and stacked-commit review. The same binary also offers optional AI helpers for commit messages, change explanations and natural-language git commands.

### How do I install lumen?

The README gives two paths: brew install jnsahaj/lumen/lumen on macOS and Linux, or cargo install lumen if you have a Rust toolchain. git is required, while fzf and mdcat are optional and only needed for specific commands.

### Can I use lumen without configuring an AI provider?

Yes. The README states that the diff viewer does not require configuring a provider, and that only the AI helpers for commit messages, explanations and generated git commands need one. Those AI commands are the only part that requires network access.

### Does lumen support reviewing GitHub pull requests?

Yes. lumen diff --pr 123, a full pull request URL, or lumen diff --detect-pr for the PR attached to the current branch all open a PR in the viewer, and the README says marking a file as viewed with the space keybinding syncs with GitHub. The README does not document equivalent support for other forges.

### Which languages get syntax highlighting in lumen?

Highlighting comes from tree-sitter grammars compiled into the binary. The Cargo.toml lists TypeScript, JavaScript, Rust, JSON, Python, Go, CSS, HTML, TOML, Bash, Markdown, C#, Ruby, Elixir, Java, Zig, C and C++, so anything outside that set renders without highlighting.

## Sources

- [Issues](https://github.com/jnsahaj/lumen/issues)
- [jnsahaj/lumen on GitHub](https://github.com/jnsahaj/lumen)
- [License: MIT](https://github.com/jnsahaj/lumen/blob/main/LICENSE)
- [README](https://github.com/jnsahaj/lumen/blob/main/README.md)
- [Releases](https://github.com/jnsahaj/lumen/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jnsahaj-lumen