commit-echo

LLM-powered CLI that learns your Git commit style and auto-suggests personalized commit messages.

Features

• Style learning — Adapts to your commit conventions over time by analyzing your history
• Multi-provider — Works with OpenAI, Anthropic, Ollama, and OpenAI-compatible endpoints
• Interactive setup — Guided wizard to configure your provider and model
• Git hook integration — Optional managed prepare-commit-msg and post-commit hooks from commit-echo init --install-hook, with reversible removal via --uninstall-hook
• Batch mode — Process many repositories from one command with commit-echo batch
• Shell completions — Generate bash, zsh, fish, or PowerShell completion scripts with commit-echo completion
• Non-destructive — Review and edit suggestions before committing

Installation

npm install -g @404-pf/commit-echo

Development

To build and run the CLI locally without a global install:

npm install
npm run build
node dist/index.js suggest

See CONTRIBUTING.md for the full setup and contribution workflow.

Usage

# Full flow: diff, suggest, pick, commit
commit-echo

# Auto-accept and commit first suggestion
commit-echo --yes

# Interactive setup wizard
commit-echo init

# Interactive setup and install the commit-echo hooks
commit-echo init --install-hook

# Remove commit-echo hooks and restore any hooks that were already present (from inside a Git repository)
commit-echo init --uninstall-hook

# Generate suggestions without committing
commit-echo suggest

# Auto-select first suggestion (no commit)
commit-echo suggest --yes

# View learned style profile
commit-echo history

# Process repositories in a directory tree
commit-echo batch . --recursive

# Generate a shell completion script
commit-echo completion bash

# PowerShell: install for the current session
commit-echo completion powershell | Out-String | Invoke-Expression

# Update a single config value
commit-echo config set model gpt-4o

Note: The non-interactive flags --yes, -y, and --auto expect staged changes (run git add). If no staged changes are found when auto-committing is requested, the command will print an error and exit with a non-zero status.

batch Behavior

Batch mode uses the same Git diff helpers as suggest for each repository. Repositories are committed only when they have staged changes. Tracked unstaged changes and non-ignored untracked files are detected and reported as Unstaged only, but are skipped until they are staged with git add. When staged and unstaged/untracked changes are mixed, batch analyzes and commits only the staged diff and leaves the remaining worktree changes untouched.

suggest Options

| Flag | Default | Description | |---|---|---| | --commit | false | Commit the selected suggestion instead of just displaying it | | -y, --yes | false | Automatically select the first suggestion and skip prompts | | --auto | false | Alias for --yes | | -v, --verbose | false | Print diagnostic information (model, style profile stats, truncation) | | -d, --show-diff | false | Print the diff content that will be sent to the LLM | | -m, --model <model> | — | Override the configured LLM model for this invocation | | --max-diff-size <n> | — | Override the configured maximum diff size for this invocation | | --stream | false | Stream suggestions as they are generated (progressive output) | | -n, --dry-run | false | Show the LLM input without generating suggestions | | --no-commit | — | Deprecated alias; suggest already skips committing unless --commit is passed |

Note: The --stream flag is supported for OpenAI-compatible and Anthropic providers. Cohere does not support streaming.

Command Reference

| Command | Description | |---|---| | commit-echo batch [directory] | Process multiple git repositories in batch mode | | commit-echo completion [shell] | Generate a shell completion script for bash, zsh, fish, or PowerShell | | commit-echo config | View the current configuration | | commit-echo config set <key> <value> | Update one configuration value |

Requirements

• Node.js >= 24.0.0
• A Git repository with staged changes
• An API key for your chosen LLM provider

Configuration

Run commit-echo init to configure your provider and model. Configuration is stored in config.json inside an OS-specific config directory:

| OS | Config directory | |---|---| | Linux | ~/.config/commit-echo (or $XDG_CONFIG_HOME/commit-echo if set) | | macOS | ~/Library/Application Support/commit-echo | | Windows | %APPDATA%\commit-echo (falls back to ~/.config/commit-echo if APPDATA is unset) |

History and learned style data live alongside the config in the same directory (history.jsonl).

To add a custom provider, create a file in the src/providers directory (e.g., src/providers/my-provider.ts) and add it to the BUILTIN_PROVIDERS list. Then, wire it into the createProvider() function. You can also use the __custom__ provider key for an OpenAI-compatible endpoint, configure the base URL with commit-echo init (or COMMIT_ECHO_BASE_URL), and set CUSTOM_API_KEY to the endpoint's API key.

If you want git commit to prefill the first suggestion automatically, run commit-echo init --install-hook from inside a Git repository. This installs both a prepare-commit-msg hook (prefills the first suggestion) and a post-commit hook (logs the committed message for style learning), and prints both installed paths. Run commit-echo init --uninstall-hook from inside the same Git repository to remove commit-echo-managed hooks and restore any hooks that were present before installation. The hooks skip merge commits, cherry-picks, amend flows, and any commit where a message was already supplied.

Options

| Option | Default | Description | |---|---|---| | provider | — | LLM provider key (e.g., openai, anthropic, ollama) | | model | — | Model name to use for generation | | historySize | 50 | Number of recent commits to learn style from | | maxDiffSize | 4000 | Maximum diff size (in characters) sent to the LLM. Diffs exceeding this limit are intelligently truncated — file headers are preserved while line-level content is dropped from overflow files. Adjust upward for large refactors or generated-file changes. |

Environment Variable Overrides

All scalar configuration options can be overridden with COMMIT_ECHO_* environment variables. Environment variables take precedence over values in config.json, which is useful for CI pipelines, testing, and switching between projects without editing the config file. (Prompt templates are not overridable via environment variables.)

| Config Option | Environment Variable | |---|---| | provider | COMMIT_ECHO_PROVIDER | | model | COMMIT_ECHO_MODEL | | baseUrl | COMMIT_ECHO_BASE_URL | | apiKey | COMMIT_ECHO_API_KEY | | historySize | COMMIT_ECHO_HISTORY_SIZE | | maxDiffSize | COMMIT_ECHO_MAX_DIFF_SIZE |

Example (macOS / Linux):

export COMMIT_ECHO_PROVIDER=anthropic
export COMMIT_ECHO_MODEL=claude-sonnet-4-20250514
export COMMIT_ECHO_API_KEY=sk-ant-...
commit-echo suggest

Adjusting maxDiffSize

maxDiffSize controls how many diff characters are sent to the LLM. When a staged diff is larger than the limit, commit-echo preserves file headers and trims overflow file bodies before generating suggestions. The status output reports this as truncation, so raise the value when important context is being omitted.

For typical feature or fix commits, the default 4000 characters keeps prompts small. For large refactors, generated files, or commits that touch many files, set maxDiffSize to 10000 or higher in config.json (see the config directory for your OS above):

{
  "maxDiffSize": 10000
}

Custom Prompt Templates

You can override the built-in system and user prompts by setting systemPromptTemplate and/or userPromptTemplate in config.json. This is useful for enforcing project-specific commit conventions (e.g., Jira ticket prefixes, Gerrit Change-Id footers, Signed-off-by lines).

Run commit-echo init and answer "Yes" when asked about custom prompt templates, or edit config.json directly:

{
  "systemPromptTemplate": "You are a commit assistant for the Acme project.\nAlways include a Jira ticket reference.\n\n{{profile}}",
  "userPromptTemplate": "Generate 3 conventional commits for this diff on branch {{branch}}:\n\n{{diff}}"
}

Template Variables

| Variable | Description | |----------|-------------| | {{diff}} | The git diff text | | {{profile}} | The learned style profile summary | | {{branch}} | Current git branch name | | {{message}} | (reserved) Previous commit message context |

If a custom template is not set, the built-in prompt is used as a fallback.

Quickstart

Environment

Set the API key for the provider you plan to use before running the setup wizard or generating suggestions. The table below lists all built-in providers, their API key environment variables, and whether a key is required.

| Provider key | Display name | API key env var | Required? | |---|---|---|---| | openai | OpenAI | OPENAI_API_KEY | Yes | | openrouter | OpenRouter | OPENROUTER_API_KEY | Yes | | anthropic | Anthropic | ANTHROPIC_API_KEY | Yes | | google | Google Gemini | GOOGLE_API_KEY | Yes | | mistral | Mistral | MISTRAL_API_KEY | Yes | | groq | Groq | GROQ_API_KEY | Yes | | cohere | Cohere | COHERE_API_KEY | Yes | | deepseek | DeepSeek | DEEPSEEK_API_KEY | Yes | | ollama | Ollama | OLLAMA_API_KEY | No / optional for local Ollama | | together | Together AI | TOGETHER_API_KEY | Yes | | fireworks | Fireworks AI | FIREWORKS_API_KEY | Yes | | example | Example (no API key) | — | No |

Note: Ollama uses the local server at http://localhost:11434/v1 and normally does not require an API key; the env var is only relevant if your local setup expects one.

Tip: The example provider returns canned responses and requires no API key. It is useful for local testing and trying out commit-echo without connecting to an LLM. Set provider to example in your config to use it.

Example (macOS / Linux):

export OPENAI_API_KEY=sk-example

Example (Windows PowerShell):

$env:OPENAI_API_KEY = "sk-example"

Example (Windows CMD):

set OPENAI_API_KEY=sk-example

Full flow: review staged changes and commit

git add .
commit-echo

Sample output:

commit-echo
  1. feat: add release summary command
  2. fix: guard empty commit history
  3. docs: clarify init workflow

Interactive setup

commit-echo init

What it does:

• lets you pick a provider
• helps you choose a model
• saves the config to config.json in the OS-specific config directory (see Configuration above)

Generate suggestions without committing

commit-echo suggest

commit-echo suggest --no-commit is still accepted as a deprecated compatibility alias.

Sample output:

Suggestions generated:
  1. fix: handle empty staged diff
  2. test: cover custom provider validation
  3. chore: refresh package metadata

Stream suggestions as they are generated

Use --stream to print LLM output incrementally instead of waiting behind a spinner. Supported for OpenAI-compatible and Anthropic providers; use non-streaming mode for Cohere. Pair with --yes for a non-interactive workflow that streams output and auto-commits the first suggestion.

commit-echo suggest --stream
commit-echo suggest --stream --yes

Inspect suggestion diagnostics with --verbose

Use verbose mode when you want to confirm which model handled the request, how much commit history was folded into the style profile, or whether the diff had to be truncated before sending it to the provider.

commit-echo suggest --verbose

Sample output:

Suggestions generated:
Model: gpt-4o
Style profile: 5 commit(s), avg length 31.4, imperative rate 80.0%, common prefixes: feat, fix, docs
Truncation: not applied
  1. fix: handle empty staged diff
  2. test: cover custom provider validation
  3. chore: refresh package metadata

Verbose fields:

• Model shows the resolved model name after any --model override is applied.
• Style profile summarizes the recent commit history used for tone and structure: how many commits were sampled, the average subject length, the share of imperative subjects, and the most common prefixes.
• Truncation tells you whether maxDiffSize trimmed the staged diff before generation. If truncation happens, the CLI also prints a warning with the original and reduced character counts.

View learned style history

commit-echo history

Sample output:

Recent commit style
- prefix frequency: fix, feat, docs
- average subject length: 42
- recent bodies: 6

Troubleshooting

• No configuration found — run commit-echo init first.
• No changes detected — stage files with git add or make an unstaged edit before running commit-echo suggest.
• Provider auth errors — confirm the matching environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, or your custom provider key) is set in the same shell session.
• Wrong repository context — run the command inside a Git repository so commit-echo can read the diff and history.

License

MIT