Quickstart

---
name: lumen
description: Use this skill when the user wants to view git diffs beautifully, generate commit messages with AI, explain code changes, or generate git commands from natural language.
---

# lumen Plugin

Beautiful git diff viewer with AI-powered commit message generation and git command generation. Generate meaningful commits, explain changes, and execute git commands from natural language.

## Commands

### Git Diff
- `lumen diff view` — View git diff with beautiful formatting

### AI Commit Generation
- `lumen commit draft` — Generate commit message from staged changes

### Git Command Generation
- `lumen git operate` — Generate and execute git commands from natural language

### Change Analysis
- `lumen changes explain` — Explain changes with AI

### Utility
- `lumen self version` — Print lumen version
- `lumen _ _` — Passthrough to lumen CLI

## Usage Examples
- "Show me a beautiful diff of my changes"
- "Generate a commit message for staged changes"
- "Explain what changed in this commit"
- "Squash the last 3 commits"
- "Generate a git command to revert the last commit"

## Installation

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

Or via Cargo:
```bash
cargo install lumen
```

## Examples

```bash
# View diff of current changes
lumen diff view

# View diff of specific file
lumen diff view src/main.ts

# View staged changes
lumen diff view --cached

# Generate commit message for staged changes
lumen commit draft

# Generate commit message with context
lumen commit draft --context "match brand guidelines"

# Explain changes with AI
lumen changes explain

# List and explain changes with fzf
lumen changes explain --list

# Generate git command from natural language
lumen git operate "squash the last 3 commits into 1 with the message 'squashed commit'"

# Generate and execute git command
lumen git operate "revert the last commit"

# Any lumen command with passthrough
lumen _ _ diff
lumen _ _ draft --context "fix bug in authentication"
```

## Key Features
- **Beautiful diff viewer** — Visual diff formatting without AI configuration
- **AI commit generation** — Generate meaningful commit messages from staged changes
- **Natural language git commands** — Ask for git operations in plain English
- **Change explanation** — AI-powered explanations of code changes
- **Interactive mode** — Confirmation before executing dangerous operations
- **Safety warnings** — Warns about potentially dangerous git operations
- **Multiple AI providers** — Supports OpenAI, Anthropic, and other providers
- **Context-aware** — Add context to improve commit message quality
- **Optional dependencies** — fzf for list mode, mdcat for pretty formatting

## AI Features
AI features (draft, explain, operate) require configuration:
```bash
lumen configure
```

This guides you through:
1. Selecting an AI provider (OpenAI, Anthropic, etc.)
2. Entering your API key (optional if using environment variable)
3. Specifying a custom model name (optional)

Configuration saved to: `~/.config/lumen/lumen.config.json`

## Notes
- The `diff` command works without any AI configuration
- AI features require `lumen configure` to set up your provider and API key
- Uses fzf for interactive selection in `lumen explain --list`
- Uses mdcat for pretty markdown output formatting
- Git commands generated by `operate` show explanations and warnings before execution
- Dangerous operations require confirmation before execution