commit-coach

AI-powered CLI for generating high-signal commit messages and pull request summaries from git diff.

Why commit-coach?

• Keeps commit messages consistent without forcing templates.
• Works with AI when available and falls back to deterministic heuristics.
• Multi-provider LLM support: OpenAI, Groq, Ollama, Gemini, DeepSeek, Mistral, OpenRouter.
• Supports Korean and English output.

Install

Global install

# npm
npm install -g @lizzy_o3o/commit-coach

# pnpm
pnpm add -g @lizzy_o3o/commit-coach

# yarn
yarn global add @lizzy_o3o/commit-coach

# bun
bun add -g @lizzy_o3o/commit-coach

Run without installing

npx @lizzy_o3o/commit-coach --help
# or
pnpx @lizzy_o3o/commit-coach --help

Available aliases

After install, these commands are all equivalent:

commit-coach --help
ccoach --help
ccm --help

cc is also registered but may conflict with clang on macOS. Prefer ccm.

Quick Start

# 1) install
npm install -g @lizzy_o3o/commit-coach

# 2) first-time setup (choose provider, API key, model, language)
ccm init

# 3) generate commit message
git add .
ccm msg

# 4) generate PR summary
ccm pr --base main

Usage

ccm msg — Commit message

Generate one recommended commit message from staged changes.

ccm msg
ccm msg --lang ko
ccm msg --style conventional --max 72
ccm msg --verbose

ccm pr — PR summary

Generate PR title/body from branch diff.

ccm pr --base main
ccm pr --lang en
ccm pr --verbose

PR summaries include file-level change highlights:

## 변경 요약
- src/app/page.tsx: ContentRow 제거, footer 텍스트 변경

ccm init — Setup wizard

Interactive setup for first-time use. This is the recommended entry point.

ccm init          # local config
ccm init -g       # global config
ccm init --defaults  # skip wizard, use defaults

The wizard walks you through:

1. Scope — local (.commit-coach.json) or global (~/.commit-coach.json)
2. Provider — openai, groq, ollama, gemini, deepseek, mistral, openrouter, or custom
3. API key — skipped for ollama (runs locally)
4. Model — fetched from provider API, or enter manually
5. Language — ko / en

ccm config:set — Update config

ccm config:set language ko
ccm config:set provider groq
ccm config:set model llama-3.3-70b-versatile
ccm config:set apiKey gsk_...
ccm config:set -g language en    # update global config

ccm hook:install — Git hook

Install a prepare-commit-msg hook that shows recommendations on every commit.

ccm hook:install

Supported Providers

| Provider | API key required | Notes | |---|---|---| | OpenAI | Yes | Default provider | | Groq | Yes | Fast inference | | Ollama | No | Local, no API key needed | | Gemini | Yes | Google AI | | DeepSeek | Yes | | | Mistral | Yes | | | OpenRouter | Yes | Access 300+ models | | Custom | Yes | Any OpenAI-compatible API via baseURL |

Configuration

Precedence

1. built-in defaults
2. global config: ~/.commit-coach.json
3. local config: ./.commit-coach.json

Local overrides global.

Example config

{
  "language": "ko",
  "commitStyle": "conventional",
  "maxSubjectLength": 72,
  "scopes": ["core", "api", "web", "docs"],
  "provider": "groq",
  "model": "llama-3.3-70b-versatile",
  "apiKey": "gsk_..."
}

AI vs Fallback

• If a provider and API key are configured, AI output is used.
• If not, commit-coach falls back to local heuristics.
• Use --verbose to see which mode was used.

You can also set API key via environment variable (fallback):

export OPENAI_API_KEY="your-key"

CI / Automation

msg/pr require config to exist. In CI, either:

# option 1: create config non-interactively
ccm init --defaults

# option 2: skip the config check
COMMIT_COACH_SKIP_ONBOARDING=1 ccm msg

# option 3: disable branding/animation
COMMIT_COACH_BRAND=0 COMMIT_COACH_ANIMATE=0 ccm msg

Global Options

ccm --no-brand msg               # hide banner
ccm --theme sunset config:init   # change brand theme

Contributing

Contributions are welcome.

git clone https://github.com/reeseo3o/commit-coach.git
cd commit-coach
npm install
npm run test && npm run typecheck && npm run build

1. Fork the repository
2. Create a feature branch
3. Add/update tests
4. Run npm run test && npm run typecheck && npm run build
5. Open a pull request

Security

• Never commit secrets (API keys, credentials, .env values).
• Keep local credentials out of tracked files.
• .commit-coach.json is in .gitignore by default.

License

MIT — see LICENSE