lumen: A Rust TUI for Side-by-Side Diffs, PR Review, and AI Commit Drafting

What lumen Solves and Who It Is For

lumen addresses a specific pain: reviewing code changes without leaving the terminal or switching to a web browser. It is a TUI (terminal user interface) that displays git diffs side by side, with syntax highlighting powered by tree-sitter. The target user is a developer who already works with git from the command line and wants a richer view than `git diff` provides, but does not want to open a GUI tool or a GitHub tab. The README positions it as a tool for reviewing diffs, commits, branches, and GitHub pull requests. It also bundles optional AI features that generate commit messages, explain changes, and even translate natural language into git commands. That makes it attractive to developers who want to speed up commit hygiene and code review, especially those working in a terminal-centric environment. The tool is written in Rust and distributed as a single static binary, which suggests a focus on performance and ease of deployment. The documentation claims it stays responsive on multi-thousand-line diffs, a claim that is plausible given the Rust implementation but which I could not verify from the repository alone.

The Core Mechanism: Side-by-Side Diffing with Tree-Sitter

At its heart, lumen is a diff renderer. It takes a git diff and presents it in a side-by-side layout inside the terminal. The syntax highlighting relies on tree-sitter, which parses code into a syntax tree, allowing for accurate highlighting of added and removed lines across many languages. The viewer supports character-level selection via mouse click-drag, or line-level selection by clicking on line numbers. This selection is not just for copying; it feeds into an annotation system. You can annotate a selected range, a whole hunk, or an entire file. Annotated lines get a gutter indicator, and the `I` key opens a view to manage, edit, or export annotations. The viewer also tracks viewed files per commit, which is useful when reviewing a series of commits. The keybindings are vim-ish: `j` and `k` navigate, `{` and `}` jump between hunks, and `space` marks a file as viewed. This is a keyboard-first design, but mouse support exists for selection and clicking arrows in the header to move between commits in stacked mode.

Getting It Running: Installation and Basic Commands

Installation is straightforward for macOS and Linux via Homebrew: `brew install jnsahaj/lumen/lumen`. For other systems, you can use Cargo: `cargo install lumen`. The prerequisites are git, and optionally fzf for `lumen explain --list` and mdcat for pretty output formatting. Once installed, the main entry point is `lumen diff`. Running it without arguments shows uncommitted changes. You can pass a commit range like `lumen diff HEAD~1` or `lumen diff main..feature/A`. A notable feature is direct GitHub PR review: `lumen diff --pr 123` or even `lumen diff https://github.com/owner/repo/pull/123` opens the PR's diff inside the terminal. There is also `--detect-pr` to guess the PR associated with the current branch. Filtering to specific files is possible with `--file src/main.rs` repeated. Watch mode (`--watch`) auto-refreshes on file changes, and `--stacked` reviews a range of commits one by one. A `--focus` flag jumps to a file on open, and `--wrap` soft-wraps long lines. The viewer's behavior is configurable through a config file at `~/.config/lumen/lumen.config.json`, where you can set a theme or other options. The README shows a theme priority: CLI flag > config file > `LUMEN_THEME` env var > OS auto-detect.

AI Features: Commit Messages, Explanations, and Git Commands

The AI features are optional and require configuring a provider. The README lists 10+ providers, though it does not enumerate them all in the snippet. Setup is interactive: run `lumen configure` to set provider, API key, and model. The settings are saved to the same config file. Once configured, `lumen draft` generates a commit message based on staged changes. The example shows an input of staged changes producing `feat(button.tsx): Update button color to blue`. You can add context with `--context "match brand guidelines"` to steer the output. There is also a command to generate git commands from natural language, but the README snippet cuts off before showing the exact syntax. Another feature is `lumen explain`, which presumably explains changes; the `--list` variant requires fzf. These AI helpers are separate from the diff viewer, which works without any AI configuration. This separation is a sensible design: the core review functionality does not depend on an external API, so you can use lumen purely as a diff viewer without sending code to a third party.

Limitations and Failure Modes

lumen has clear boundaries. The AI features are not core; they require an API key and an internet connection, and they send your code or diffs to an external provider. If you work on proprietary code, that is a real consideration. The README does not provide details on data handling or privacy for AI requests. Another limitation is that the diff viewer is terminal-only. It is not a web-based tool, so it will not help with asynchronous, distributed code review where reviewers are not at the same machine. The annotation system is local; there is no mention of syncing annotations to GitHub or a central server, except for marking files as viewed on a PR, which syncs with GitHub. The `space` keybinding marks a file as viewed, and the README says this syncs with GitHub. But general annotations appear to be local only. Also, the tool depends on git being installed, and for PR review it needs network access to GitHub. If you use a different hosting service like GitLab, the README does not mention support. The stacked mode is useful for a range of commits, but it is not a substitute for a full code review workflow with comments and approvals.

Alternatives: How lumen Differs from Other Tools

The most direct alternative is a GUI diff tool like Meld or Kaleidoscope, or a terminal pager like `delta` (a Rust-based diff highlighter). The key difference is that lumen is a TUI with interactive features: you can navigate hunks, select text, annotate, and mark files as viewed. `delta` is a pager that formats git output but does not provide a side-by-side interactive view with annotations. Another alternative is using GitHub's web interface for PR review, which offers inline comments, approval workflows, and team collaboration. lumen offers a subset of that: you can view the PR diff and mark files as viewed, but you cannot leave comments that others see, because annotations are local. The README mentions integration with coding agents, but the details are cut off. For those who use Jujutsu (jj), lumen explicitly works with it, which is a differentiator since many git tools do not support jj. So lumen sits between a simple diff formatter and a full web-based review platform, aiming for speed and keyboard efficiency.

Configuration, Themes, and Maintenance Considerations

Configuration is stored in a JSON file at `~/.config/lumen/lumen.config.json`. The README shows an example with a `theme` key. Themes include preset names like `dracula`, `catppuccin-mocha`, `nord`, `one-dark`, and `gruvbox-dark`. You can set the theme via CLI flag, config file, or environment variable `LUMEN_THEME`. Precedence is clear: CLI flag wins over config file, which wins over environment variable, with OS auto-detect as the fallback. This three-level system is flexible, but it means you need to remember the precedence order when debugging why a theme is not applied. The project is actively maintained, with releases as recent as v2.32.0 in July 2026. The repository is not archived, and the last push is recent. The license is MIT, which is permissive for commercial use. Maintenance cost for a user is low: it is a single binary, so upgrades are simple via `cargo install lumen` or Homebrew. The main cost is keeping up with new releases, which appear frequent (three releases in a month). For an organization, the AI features introduce a dependency on external providers, which can change pricing or availability.

The Verdict: Who Should Adopt lumen and What to Check

lumen is a solid choice for developers who want a fast, interactive diff viewer in the terminal, especially those who review GitHub PRs without switching to a browser. The side-by-side view with tree-sitter highlighting is a step up from plain `git diff`, and the annotation system, even if local, is useful for personal notes during review. The AI commit message generator is a convenience, but it is not the reason to adopt lumen; the diff viewer is. If you are a developer who uses Jujutsu, lumen's explicit support is a plus. However, if your team relies on shared, persistent review comments, lumen will not replace a code review platform. Before adopting, verify that your Git hosting service is supported (the README mentions GitHub PRs specifically), and test the annotation workflow to see if it meets your needs. Also, check the configuration file format to ensure it supports the options you want, such as soft-wrap, which can also be set in the config. The project is under active development, so expect changes. If you need a terminal diff viewer that is fast and keyboard-driven, lumen is worth a try.

Editorial conclusion

lumen is for developers who live in the terminal and want a fast, syntax-highlighted diff viewer that also handles GitHub PR review and stacked commits. It is not for those who need a full IDE-like review experience or who are unwilling to manage AI provider keys for the optional features. Before adopting, verify that your Git workflow (including Jujutsu) is supported by the current release, and check the configuration file format and theme options. If you need native CI integration or multi-user review, look elsewhere. lumen's strength is its single-binary, keyboard-driven approach to local and PR diffs.

Official sources

1. Issues
2. jnsahaj/lumen on GitHub
3. License: MIT
4. README
5. Releases