{"id":21584665,"url":"https://github.com/jnsahaj/lumen","last_synced_at":"2026-10-29T21:17:09.606Z","repository":{"id":259956145,"uuid":"879874959","full_name":"jnsahaj/lumen","owner":"jnsahaj","description":"Beautiful git diff viewer, generate commits with AI, get summary of changes, all from the CLI","archived":false,"fork":false,"pushed_at":"2026-09-17T14:15:58.000Z","size":577,"stargazers_count":2899,"open_issues_count":78,"forks_count":162,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-10-27T09:43:12.532Z","etag":null,"topics":["cli","commit","git","llm","openai","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jnsahaj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-28T17:42:55.000Z","updated_at":"2026-10-26T21:57:27.000Z","dependencies_parsed_at":"2024-12-12T01:21:39.330Z","dependency_job_id":"e58a8773-5b8e-4868-8390-11bd57f37e37","html_url":"https://github.com/jnsahaj/lumen","commit_stats":null,"previous_names":["jnsahaj/lumen"],"tags_count":54,"template":false,"template_full_name":null,"purl":"pkg:github/jnsahaj/lumen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnsahaj%2Flumen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnsahaj%2Flumen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnsahaj%2Flumen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnsahaj%2Flumen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jnsahaj","download_url":"https://codeload.github.com/jnsahaj/lumen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jnsahaj%2Flumen/sbom","scorecard":null,"funding_links":["https://github.com/sponsors/jnsahaj"],"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":346510206,"owners_count":38561585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-10-03T21:59:58.778Z","status":"online","status_checked_at":"2026-10-27T02:00:05.503Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","commit","git","llm","openai","rust"],"created_at":"2024-11-24T15:01:27.114Z","updated_at":"2026-10-27T20:23:38.121Z","avatar_url":"https://github.com/jnsahaj.png","language":"Rust","funding_links":[],"categories":["Rust","AI","CLIs","Lovely Commands","\u003ca name=\"Rust\"\u003e\u003c/a\u003eRust","Language and Tooling"],"sub_categories":["Version Control"],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"https://github.com/user-attachments/assets/896f9239-134a-4428-9bb5-50ea59cdb5c3\" alt=\"lumen\" /\u003e\u003c/p\u003e\n\n# lumen\n\nA fast terminal diff viewer and code review TUI, written in Rust.\n\n[![Crates.io Total Downloads](https://img.shields.io/crates/d/lumen?label=downloads%20%40crates.io)](https://crates.io/crates/lumen)\n[![GitHub Releases](https://img.shields.io/github/downloads/jnsahaj/lumen/total?label=dowloads%20%40releases)](https://github.com/jnsahaj/lumen/releases)\n![GitHub License](https://img.shields.io/github/license/jnsahaj/lumen)\n![Crates.io Size](https://img.shields.io/crates/size/lumen)\n\nReview `git diff`, commits, branches, or GitHub PRs side-by-side without leaving your terminal. Ships as a single static Rust binary and stays snappy on multi-thousand-line diffs.\n\n- Side-by-side diff viewer with tree-sitter syntax highlighting\n- Review GitHub Pull Requests with `lumen diff --pr 123`\n- Annotate selections, hunks, or whole files\n- Watch mode and stacked-commit review\n- Optional AI commit messages and change explanations (10+ providers)\n- Works with Git and Jujutsu (jj)\n\n[![Demo](https://github.com/user-attachments/assets/dc425871-3826-4368-88d8-931b9403f0ec)](https://github.com/user-attachments/assets/70d07324-8394-423c-bbc3-9460ed84877b)\n\n## Table of Contents\n- [Getting Started](#getting-started-)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n- [Usage](#usage-)\n  - [Visual Diff Viewer](#visual-diff-viewer)\n- [AI Features](#ai-features-)\n  - [Configuration](#configuration)\n  - [Generate Commit Messages](#generate-commit-messages)\n  - [Generate Git Commands](#generate-git-commands)\n  - [Explain Changes](#explain-changes)\n  - [Tips \u0026 Tricks](#tips--tricks)\n  - [AI Providers](#ai-providers)\n- [Coding Agent Integrations](#coding-agent-integrations-)\n- [Advanced Configuration](#advanced-configuration-)\n  - [Configuration File](#configuration-file)\n  - [Configuration Precedence](#configuration-precedence)\n\n## Getting Started 🔅\n\n### Prerequisites\nBefore you begin, ensure you have:\n1. `git` installed on your system\n2. [fzf](https://github.com/junegunn/fzf) (optional) - Required for `lumen explain --list` command\n3. [mdcat](https://github.com/swsnr/mdcat) (optional) - Required for pretty output formatting\n\n### Installation\n\n#### Using Homebrew (MacOS and Linux)\n```bash\nbrew install jnsahaj/lumen/lumen\n```\n\n#### Using Cargo\n\u003e [!IMPORTANT]\n\u003e `cargo` is a package manager for `rust`,\n\u003e and is installed automatically when you install `rust`.\n\u003e See [installation guide](https://doc.rust-lang.org/cargo/getting-started/installation.html)\n```bash\ncargo install lumen\n```\n\n## Usage 🔅\n\n### Visual Diff Viewer\n\nLaunch an interactive side-by-side diff viewer in your terminal:\n\u003cimg width=\"3456\" height=\"2122\" alt=\"image\" src=\"https://github.com/user-attachments/assets/757e1187-1615-4e90-bee2-5a1f59ec0960\" /\u003e\n\n```bash\n# View uncommitted changes\nlumen diff\n\n# View changes for a specific commit\nlumen diff HEAD~1\n\n# View changes between branches\nlumen diff main..feature/A\n\n# View changes in a GitHub Pull Request\nlumen diff --pr 123 # (--pr is optional)\nlumen diff https://github.com/owner/repo/pull/123\n\n# Open the PR associated with the current branch\nlumen diff --detect-pr\n\n# Filter to specific files\nlumen diff --file src/main.rs --file src/lib.rs\n\n# Watch mode - auto-refresh on file changes\nlumen diff --watch\n\n# Stacked mode - review commits one by one\nlumen diff main..feature --stacked\n\n# Jump to a specific file on open\nlumen diff --focus src/main.rs\n\n# Soft-wrap long lines (also settable in lumen.config.json)\nlumen diff --wrap\n```\n\n#### Stacked Diff Mode\n\nReview a range of commits one at a time with `--stacked`:\n\n```bash\nlumen diff main..feature --stacked\nlumen diff HEAD~5..HEAD --stacked\n```\n\nThis displays each commit individually, letting you navigate through them:\n- `ctrl+h` / `ctrl+l`: Previous / next commit\n- Click the `‹` / `›` arrows in the header\n\nThe header shows the current commit position, SHA, and message. Viewed files are tracked per commit, so your progress is preserved when navigating.\n\nWhen viewing a PR, you can mark files as viewed (syncs with GitHub) using the `space` keybinding.\n\n#### Theme Configuration\n\nCustomize the diff viewer colors with preset themes:\n\n```bash\n# Using CLI flag\nlumen diff --theme dracula\n\n# Using environment variable\nLUMEN_THEME=catppuccin-mocha lumen diff\n\n# Or set permanently in config file (~/.config/lumen/lumen.config.json)\n{\n  \"theme\": \"dracula\"\n}\n```\n\n**Available themes:**\n| Theme | Value |\n|-------|-------|\n| Default (auto-detect) | `dark`, `light` |\n| Catppuccin | `catppuccin-mocha`, `catppuccin-latte` |\n| Dracula | `dracula` |\n| Nord | `nord` |\n| One Dark | `one-dark` |\n| Gruvbox | `gruvbox-dark`, `gruvbox-light` |\n| Solarized | `solarized-dark`, `solarized-light` |\n| Flexoki | `flexoki-dark`, `flexoki-light` |\n\nPriority: CLI flag \u003e config file \u003e `LUMEN_THEME` env var \u003e OS auto-detect.\n\n#### Selection \u0026 Annotations\n\n**Selection**: Click-drag in the content area for character-level selection, or on line numbers for line-level selection. Selected text can be copied or annotated.\n\n**Annotations**: Add review comments at three levels of granularity:\n- **Selection** — select lines with mouse, press `i` to annotate the selected range\n- **Hunk** — focus a hunk with `{`/`}`, press `i` to annotate the hunk\n- **File** — press `i` with no selection or hunk focus to annotate the whole file\n\nAnnotated lines display a `▍` gutter indicator. Use `I` to view, edit, delete, copy, or export all annotations.\n\n#### Keybindings\n\n- `j/k` or arrow keys: Navigate\n- `{/}`: Jump between hunks\n- `w`: Toggle watch mode\n- `tab`: Toggle sidebar\n- `space`: Mark file as viewed\n- `e`: Open file in editor\n- `y`: Copy selection (or filename)\n- `i`: Annotate selection / hunk / file\n- `I`: View all annotations\n- `ctrl+h/l`: Previous/next commit (stacked mode)\n- `?`: Show all keybindings\n\n## AI Features 🔅\n\nLumen also bundles optional AI helpers for commit messages, explanations, and natural-language git commands. These require configuring an AI provider — the diff viewer above does not.\n\n### Configuration\n\nRun `lumen configure` for interactive setup (provider, API key, model). Settings are saved to `~/.config/lumen/lumen.config.json`.\n\n### Generate Commit Messages\n\nCreate meaningful commit messages for your staged changes:\n\n```bash\n# Basic usage - generates a commit message based on staged changes\nlumen draft\n# Output: \"feat(button.tsx): Update button color to blue\"\n\n# Add context for more meaningful messages\nlumen draft --context \"match brand guidelines\"\n# Output: \"feat(button.tsx): Update button color to align with brand identity guidelines\"\n```\n\n### Generate Git Commands\n\nAsk Lumen to generate Git commands based on a natural language query:\n\n```bash\nlumen operate \"squash the last 3 commits into 1 with the message 'squashed commit'\"\n# Output: git reset --soft HEAD~3 \u0026\u0026 git commit -m \"squashed commit\" [y/N]\n```\n\nThe command will display an explanation of what the generated command does, show any warnings for potentially dangerous operations, and prompt for confirmation before execution.\n\n### Explain Changes\n\nUnderstand what changed and why:\n\n```bash\n# Working directory or staged changes\nlumen explain\nlumen explain --staged\n\n# Specific commits or ranges\nlumen explain HEAD\nlumen explain HEAD~3..HEAD\nlumen explain main..feature/A\n\n# Ask specific questions\nlumen explain --query \"What's the performance impact of these changes?\"\n\n# Interactive commit selection (requires: fzf)\nlumen explain --list\n```\n\n### Tips \u0026 Tricks\n\n```bash\n# Copy commit message to clipboard (macOS / Linux)\nlumen draft | pbcopy\nlumen draft | xclip -selection c\n\n# Directly commit using the generated message\nlumen draft | git commit -F -\n```\n\n[lazygit](https://github.com/jesseduffield/lazygit) integration is available — see the [user config docs](https://github.com/jesseduffield/lazygit/blob/master/docs/Config.md) for binding `lumen draft` to a custom command.\n\n### AI Providers\n\nConfigure your preferred AI provider:\n\n```bash\n# Using CLI arguments\nlumen -p openai -k \"your-api-key\" -m \"gpt-5-mini\" draft\n\n# Using environment variables\nexport LUMEN_AI_PROVIDER=\"openai\"\nexport LUMEN_API_KEY=\"your-api-key\"\nexport LUMEN_AI_MODEL=\"gpt-5-mini\"\n```\n\n#### Supported Providers\n\n| Provider | API Key Required | Models |\n|----------|-----------------|---------|\n| [OpenAI](https://platform.openai.com/docs/models) `openai` (Default) | Yes | `gpt-5.2`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-4.1`, `gpt-4.1-mini`, `o4-mini` (default: `gpt-5-mini`) |\n| [Claude](https://www.anthropic.com/pricing) `claude` | Yes | `claude-sonnet-4-5-20250930`, `claude-opus-4-5-20251115`, `claude-haiku-4-5-20251015` (default: `claude-sonnet-4-5-20250930`) |\n| [Gemini](https://ai.google.dev/) `gemini` | Yes (free tier) | `gemini-3-pro`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite` (default: `gemini-2.5-flash`) |\n| [Groq](https://console.groq.com/docs/models) `groq` | Yes (free) | `llama-3.3-70b-versatile`, `llama-3.1-8b-instant`, `meta-llama/llama-4-maverick-17b-128e-instruct`, `openai/gpt-oss-120b` (default: `llama-3.3-70b-versatile`) |\n| [DeepSeek](https://www.deepseek.com/) `deepseek` | Yes | `deepseek-chat` (V3.2), `deepseek-reasoner` (default: `deepseek-chat`) |\n| [xAI](https://x.ai/) `xai` | Yes | `grok-4`, `grok-4-mini`, `grok-4-mini-fast` (default: `grok-4-mini-fast`) |\n| [OpenCode Zen](https://opencode.ai/docs/zen) `opencode-zen` | Yes | [see list](https://opencode.ai/docs/zen#models) (default: `claude-sonnet-4-5`) |\n| [Ollama](https://github.com/ollama/ollama) `ollama` | No (local) | [see list](https://ollama.com/library) (default: `llama3.2`) |\n| [OpenRouter](https://openrouter.ai/) `openrouter` | Yes | [see list](https://openrouter.ai/models) (default: `anthropic/claude-sonnet-4.5`) |\n| [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) `vercel` | Yes | [see list](https://vercel.com/docs/ai-gateway/supported-models) (default: `anthropic/claude-sonnet-4.5`) |\n\n## Coding Agent Integrations 🔅\n\nUse lumen as the review surface for your coding agent. When the agent finishes a turn, shell-escape to lumen, annotate the diff inline, and press `s` to send your annotations back as the agent's next prompt.\n\n```\nagent finishes turn → !lumen diff → annotate → press `s`\n→ stdout returns to the agent → agent fixes your notes\n```\n\nThe mechanics are just stdin/stdout — no plugins, no extensions:\n\n- `s` in the diff TUI opens a confirmation modal. On `Enter`, lumen exits and writes the formatted annotations to stdout (the same text `y` copies to your clipboard).\n- The TUI auto-routes to `/dev/tty` when stdout is captured, so the agent receives clean text — no escape codes.\n\nWorks with anything that has a shell-escape:\n\n| Agent | How to trigger |\n|-------|----------------|\n| Claude Code | `!lumen diff` |\n| Codex | `!lumen diff` |\n| Any agent with shell access | `lumen diff` from a tool/bash call |\n\nAnnotate with `i` (selection / hunk / file), press `s` → `Enter` to send. Press `q` to dismiss without sending.\n\n## Advanced Configuration 🔅\n\n### Configuration File\nLumen supports configuration through a JSON file. You can place the configuration file in one of the following locations:\n\n1. Project Root: Create a lumen.config.json file in your project's root directory.\n2. Custom Path: Specify a custom path using the --config CLI option.\n3. Global Configuration (Optional): Place a lumen.config.json file in your system's default configuration directory:\n    - Linux/macOS: `~/.config/lumen/lumen.config.json`\n    - Windows: `%USERPROFILE%\\.config\\lumen\\lumen.config.json`\n\nLumen will load configurations in the following order of priority:\n\n1. CLI arguments (highest priority)\n2. Configuration file specified by --config\n3. Project root lumen.config.json\n4. Global configuration file (lowest priority)\n\n```json\n{\n  \"provider\": \"openai\",\n  \"model\": \"gpt-5-mini\",\n  \"api_key\": \"sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n  \"theme\": \"catppuccin-mocha\",\n  \"wrap\": true,\n  \"draft\": {\n    \"commit_types\": {\n      \"docs\": \"Documentation only changes\",\n      \"style\": \"Changes that do not affect the meaning of the code\",\n      \"refactor\": \"A code change that neither fixes a bug nor adds a feature\",\n      \"perf\": \"A code change that improves performance\",\n      \"test\": \"Adding missing tests or correcting existing tests\",\n      \"build\": \"Changes that affect the build system or external dependencies\",\n      \"ci\": \"Changes to our CI configuration files and scripts\",\n      \"chore\": \"Other changes that don't modify src or test files\",\n      \"revert\": \"Reverts a previous commit\",\n      \"feat\": \"A new feature\",\n      \"fix\": \"A bug fix\"\n    }\n  }\n}\n```\n\n### Configuration Precedence\nOptions are applied in the following order (highest to lowest priority):\n1. CLI Flags\n2. Configuration File\n3. Environment Variables\n4. Default options\n\nExample: Using different providers for different projects:\n```bash\n# Set global defaults in .zshrc/.bashrc\nexport LUMEN_AI_PROVIDER=\"openai\"\nexport LUMEN_AI_MODEL=\"gpt-5-mini\"\nexport LUMEN_API_KEY=\"sk-xxxxxxxxxxxxxxxxxxxxxxxx\"\n\n# Override per project using config file\n{\n  \"provider\": \"ollama\",\n  \"model\": \"llama3.2\"\n}\n\n# Or override using CLI flags\nlumen -p \"ollama\" -m \"llama3.2\" draft\n```\n## Contributors\n\n\u003ca href=\"https://github.com/jnsahaj/lumen/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=jnsahaj/lumen\" /\u003e\n\u003c/a\u003e\n\nMade with [contrib.rocks](https://contrib.rocks).\n\n### Interested in Contributing?\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n# Star History\n\n\u003cp align=\"center\"\u003e\n  \u003ca target=\"_blank\" href=\"https://star-history.com/#jnsahaj/lumen\u0026Date\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=jnsahaj/lumen\u0026type=Date\u0026theme=dark\"\u003e\n      \u003cimg alt=\"GitHub Star History for jnsahaj/lumen\" src=\"https://api.star-history.com/svg?repos=jnsahaj/lumen\u0026type=Date\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjnsahaj%2Flumen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjnsahaj%2Flumen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjnsahaj%2Flumen/lists"}