# lumen

> A fast terminal TUI for side-by-side git diff viewing, code review, and optional AI-powered commit messages and change explanations, written in Rust.

Lumen is an open-source, MIT-licensed terminal tool written in Rust by Sahaj Jain that brings a full-featured side-by-side diff viewer and code review TUI to the command line. It ships as a single static binary and is designed to stay snappy even on multi-thousand-line diffs. The project has accumulated over 2,800 GitHub stars since its creation in October 2024.

## What It Is

Lumen is a CLI/TUI application that lets developers review `git diff` output, commits, branches, and GitHub Pull Requests side-by-side without leaving the terminal. Beyond the visual diff viewer, it bundles optional AI helpers — for generating commit messages, explaining changes, and producing natural-language git commands — that can be connected to more than 10 different AI providers. The core diff viewer works entirely offline; AI features require a configured provider and API key.

## Core Diff Viewer Capabilities

The TUI diff viewer is the centerpiece of lumen and requires no AI configuration:

- **Side-by-side layout** with tree-sitter syntax highlighting
- **GitHub PR review** via `lumen diff --pr 123` or a full PR URL
- **Stacked diff mode** to step through a commit range one commit at a time
- **Watch mode** that auto-refreshes on file changes
- **Annotations** at selection, hunk, or file granularity with a gutter indicator
- **Theme support** including Catppuccin, Dracula, Nord, One Dark, Gruvbox, Solarized, and Flexoki variants
- **Jujutsu (jj) VCS support** in addition to standard Git

## AI Features and Provider Support

AI capabilities are opt-in and configured via `lumen configure`, CLI flags, or environment variables. Supported providers include OpenAI, Anthropic Claude, Google Gemini, Groq, DeepSeek, xAI, Ollama (local/offline), OpenRouter, Vercel AI Gateway, and OpenCode Zen — over 10 providers in total. Key AI commands:

- `lumen draft` — generates a conventional commit message from staged changes, with optional `--context` for extra guidance
- `lumen explain` — summarizes what changed and why, supports commit ranges and `--query` for targeted questions
- `lumen operate` — converts a natural-language description into a git command, shows warnings for dangerous operations, and prompts for confirmation before execution

## Coding Agent Integration

Lumen is designed to slot into agentic coding workflows. When a coding agent (Claude Code, Codex, or any shell-capable agent) finishes a turn, the developer can shell-escape into `lumen diff`, annotate the diff inline, and press `s` to send formatted annotations back to the agent as its next prompt. The TUI auto-routes to `/dev/tty` when stdout is captured, so the agent receives clean text without escape codes.

## Setup Path

Installation is available via Homebrew (`brew install jnsahaj/lumen/lumen`) or Cargo (`cargo install lumen`). Prerequisites are `git` and optionally `fzf` (for interactive commit selection) and `mdcat` (for formatted markdown output). Configuration is stored in `~/.config/lumen/lumen.config.json` on Linux/macOS or `%USERPROFILE%\.config\lumen\lumen.config.json` on Windows, with CLI flags taking highest precedence over config file and environment variables.

## Update: v2.32.0

The latest release is v2.32.0, published on July 16, 2026. The repository was last pushed on the same date, indicating active development. Since its October 2024 creation, the project has grown to 144 forks and 69 open issues, reflecting a growing contributor base and active feature requests.

## Features
- Side-by-side diff viewer with tree-sitter syntax highlighting
- GitHub Pull Request review via CLI
- Stacked diff mode for commit-by-commit review
- Watch mode with auto-refresh on file changes
- Inline annotations at selection, hunk, or file level
- AI-powered commit message generation (lumen draft)
- AI change explanation (lumen explain)
- Natural-language git command generation (lumen operate)
- 10+ AI provider support including OpenAI, Claude, Gemini, Ollama
- Coding agent integration via stdin/stdout
- Multiple color themes (Catppuccin, Dracula, Nord, Gruvbox, etc.)
- Jujutsu (jj) VCS support
- Interactive configuration via lumen configure
- JSON configuration file with layered precedence
- Single static Rust binary with no runtime dependencies

## Integrations
OpenAI, Anthropic Claude, Google Gemini, Groq, DeepSeek, xAI Grok, Ollama, OpenRouter, Vercel AI Gateway, OpenCode Zen, GitHub, lazygit, Claude Code, Codex, fzf, mdcat

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
v2.32.0

## Links
- Website: https://github.com/jnsahaj/lumen
- Documentation: https://github.com/jnsahaj/lumen#readme
- Repository: https://github.com/jnsahaj/lumen
- EveryDev.ai: https://www.everydev.ai/tools/lumen-git-diff-viewer