{"id":21584665,"url":"https://github.com/jnsahaj/lumen","last_synced_at":"2026-01-06T17:23:50.025Z","repository":{"id":259956145,"uuid":"879874959","full_name":"jnsahaj/lumen","owner":"jnsahaj","description":"Instant AI Git Commit message, Git changes summary from the CLI (no API key required)","archived":false,"fork":false,"pushed_at":"2025-06-04T09:00:34.000Z","size":274,"stargazers_count":863,"open_issues_count":13,"forks_count":29,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-10T06:10:27.366Z","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}},"created_at":"2024-10-28T17:42:55.000Z","updated_at":"2025-07-05T08:36:04.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":14,"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","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264565251,"owners_count":23628922,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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-01-02T21:14:36.836Z","avatar_url":"https://github.com/jnsahaj.png","language":"Rust","funding_links":[],"categories":["Rust","AI","CLIs","Lovely Commands","\u003ca name=\"Rust\"\u003e\u003c/a\u003eRust"],"sub_categories":[],"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[![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\nA command-line tool that uses AI to streamline your git workflow - generate commit messages, view diff and explain changes.\n![CleanShot 2025-12-30 at 02 47 04](https://github.com/user-attachments/assets/21e9d32a-de8a-40b2-b79b-3e87c9cbb9eb)\n\n## Table of Contents\n- [Features](#features-)\n- [Getting Started](#getting-started-)\n  - [Prerequisites](#prerequisites)\n  - [Installation](#installation)\n  - [Configuration (for AI features)](#configuration-for-ai-features)\n- [Usage](#usage-)\n  - [Visual Diff Viewer](#visual-diff-viewer)\n  - [Generate Commit Messages](#generate-commit-messages)\n  - [Generate Git Commands](#generate-git-commands)\n  - [Explain Changes](#explain-changes)\n  - [Interactive Mode](#interactive-mode)\n  - [Tips \u0026 Tricks](#tips--tricks)\n- [AI Providers](#ai-providers-)\n- [Advanced Configuration](#advanced-configuration-)\n  - [Configuration File](#configuration-file)\n  - [Configuration Precedence](#configuration-precedence)\n\n## Features 🔅\n\n- **Beautiful \u0026 Ergonomic Diff Viewer**: Review your code with minimal effort\n- **Smart Commit Messages**: Generate conventional commit messages for your staged changes\n- **Git History Insights**: Understand what changed in any commit, branch, or your current work\n- **Interactive Search**: Find and explore commits using fuzzy search\n- **Change Analysis**: Ask questions about specific changes and their impact\n- **Multiple AI Providers**: Supports OpenAI, Claude, Groq, Ollama, and more\n- **Flexible**: Works with any git workflow and supports multiple AI providers\n- **Rich Output**: Markdown support for readable explanations and diffs (requires: mdcat)\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 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### Configuration (for AI features)\n\nIf you want to use AI-powered features (`explain`, `draft`, `list`, `operate`), run the interactive setup:\n\n```bash\nlumen configure\n```\n\nThis will guide you through:\n1. Selecting an AI provider\n2. Entering your API key (optional if using environment variable)\n3. Specifying a custom model name (optional - press Enter to use the default)\n\nThe configuration is saved to `~/.config/lumen/lumen.config.json`.\n\n\u003e [!NOTE]\n\u003e The `diff` command works without any configuration - it's a standalone visual diff viewer.\n\n\n## Usage 🔅\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\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### Visual Diff Viewer\n\nLaunch an interactive side-by-side diff viewer in your terminal:\n\u003cimg width=\"1725\" height=\"1079\" alt=\"image\" src=\"https://github.com/user-attachments/assets/e846b8a6-d839-4e69-926c-b7ce42ce3f4c\" /\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# 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\nWhen viewing a PR, you can mark files as viewed (syncs with GitHub) using the `space` keybinding.\n\nKeybindings in the diff viewer:\n- `j/k` or arrow keys: Navigate\n- `{/}`: Jump between hunks\n- `tab`: Toggle sidebar\n- `space`: Mark file as viewed\n- `e`: Open file in editor\n- `?`: Show all keybindings\n\n### Explain Changes\n\nUnderstand what changed and why:\n\n```bash\n# Explain current changes in your working directory\nlumen explain                         # All changes\nlumen explain --staged                # Only staged changes\n\n# Explain specific commits\nlumen explain HEAD                    # Latest commit\nlumen explain abc123f                 # Specific commit\nlumen explain HEAD~3..HEAD            # Last 3 commits\nlumen explain main..feature/A         # Branch comparison\nlumen explain main...feature/A        # Branch comparison (merge base)\n\n# Ask specific questions about changes\nlumen explain --query \"What's the performance impact of these changes?\"\nlumen explain HEAD --query \"What are the potential side effects?\"\n```\n\n### Interactive Mode\n```bash\n# Launch interactive fuzzy finder to search through commits (requires: fzf)\nlumen list\n```\n\n### Tips \u0026 Tricks\n\n```bash\n# Copy commit message to clipboard\nlumen draft | pbcopy                  # macOS\nlumen draft | xclip -selection c      # Linux\n\n# View the commit message and copy it\nlumen draft | tee \u003e(pbcopy)\n\n# Open in your favorite editor\nlumen draft | code -      \n\n# Directly commit using the generated message\nlumen draft | git commit -F -           \n```\n\nIf you are using [lazygit](https://github.com/jesseduffield/lazygit), you can add this to the [user config](https://github.com/jesseduffield/lazygit/blob/master/docs/Config.md)\n```yml\ncustomCommands:\n  - key: '\u003cc-l\u003e'\n    context: 'files'\n    command: 'lumen draft | tee \u003e(pbcopy)'\n    loadingText: 'Generating message...'\n    showOutput: true\n  - key: '\u003cc-k\u003e'\n    context: 'files'\n    command: 'lumen draft -c {{.Form.Context | quote}} | tee \u003e(pbcopy)'\n    loadingText: 'Generating message...'\n    showOutput: true\n    prompts:\n          - type: 'input'\n            title: 'Context'\n            key: 'Context'\n```\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| [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## 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  \"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"}