ccommit

Generate Conventional Commit messages from staged Git changes using Claude Code CLI, OpenCode CLI, Codex CLI, Kilo Code CLI, Qwen Code CLI, or Gemini CLI.

Requirements

• Node 18+ or Bun 1.0+
• Git 2.0+
• One supported provider CLI configured and available on PATH (claude, opencode, codex, kilo, qwen, or gemini)
• Native support for Windows, macOS, and Linux

Usage

ccommit
# or from repo root
bin/ccommit

Installation

Via npm (recommended)

npm install -g @sabinm677/ccommit

From source

git clone https://github.com/sabinm677/ccommit.git
cd ccommit
chmod +x bin/ccommit
ln -sf "$(pwd)/bin/ccommit" ~/.local/bin/ccommit

If needed, add ~/.local/bin to your PATH.

Behavior

Default mode:

• Generates a commit message from staged changes
• Shows the message
• Prompts Create commit? [y/N]
• Creates commit only when you answer y or yes
• In non-interactive mode, commit is auto-cancelled unless --yes is used

Show-only mode (no commit created):

ccommit --show
ccommit -s

Override generated first line:

ccommit -m "ABC-1: Some message"
ccommit --message "ABC-1: Some message"

Choose provider for one run:

ccommit --provider opencode
ccommit -p codex
ccommit -p kilo
ccommit -p qwen
ccommit -p gemini

Persist a default provider:

ccommit --set-provider codex
ccommit -sp opencode
ccommit --set-provider=opencode

Options

• -s, --show: Generate and print message only. Do not prompt or create commit.
• -y, --yes: Create commit without interactive confirmation.
• -m, --message <text>: Replace the first line of the generated commit message. Remaining lines are preserved.
• -p, --provider <claude|opencode|codex|kilo|qwen|gemini>: Select AI provider for this run.
• -sp, --set-provider <claude|opencode|codex|kilo|qwen|gemini>: Persist default provider to config and exit.
• -h, --help: Show usage help.
• -v, --version: Show CLI version.
• --verbose: Print debug details to stderr, including provider failure diagnostics.

Commit Format

ccommit enforces Conventional Commits with a required multi-line message:

• Header format: <type>[optional scope][optional !]: <description>
• At least one non-empty body line is required
• BREAKING CHANGE: footer is supported

Example output:

feat(parser): improve prompt normalization

Improve normalization to keep body content stable across providers.

ccommit prints the selected provider in the header (including --show mode):

Generated commit message (claude):

Config

Optional config file locations:

• Windows: %APPDATA%\\ccommit\\config.json
• macOS/Linux: $XDG_CONFIG_HOME/ccommit/config.json or ~/.config/ccommit/config.json
• Override on any OS: CCOMMIT_CONFIG_PATH=/custom/path/config.json

{
  "provider": "codex",
  "providers": {
    "claude": { "command": "claude", "args": ["-p"] },
    "opencode": { "command": "opencode", "args": ["run"] },
    "codex": { "command": "codex", "args": ["exec"] },
    "kilo": { "command": "kilo", "args": ["run"] },
    "qwen": { "command": "qwen", "args": ["run"] },
    "gemini": { "command": "gemini", "args": ["-p"] }
  }
}

Precedence for provider/command settings: CLI > env > config > defaults. Default provider: claude. --set-provider updates the config file and can run outside a Git repository.

Exit Codes

• 0: success
• 1: expected error (for example not a git repo, no staged changes, provider CLI/auth/network failure)

Development

Run tests:

bun test

Build standalone executables:

bun run build:bin
# or only current platform/arch
bun run build:bin:current

Build outputs are written to dist/:

• ccommit-darwin-x64
• ccommit-darwin-arm64
• ccommit-linux-x64
• ccommit-linux-arm64
• ccommit-windows-x64.exe
• ccommit-windows-arm64.exe

Node compatibility:

• ccommit is Bun-first, but basic CLI invocation with Node remains supported (for example node bin/ccommit --version).

Test Helpers

For local testing without provider API calls:

• CCOMMIT_MOCK_MESSAGE="feat: add feature" to bypass AI provider call.
• CCOMMIT_MOCK_ERROR=AUTH to force auth error.
• CCOMMIT_MOCK_ERROR=NETWORK to force network error.

Provider env overrides:

• CCOMMIT_PROVIDER=claude|opencode|codex|kilo|qwen|gemini
• CCOMMIT_CLAUDE_CMD, CCOMMIT_CLAUDE_ARGS
• CCOMMIT_OPENCODE_CMD, CCOMMIT_OPENCODE_ARGS
• CCOMMIT_CODEX_CMD, CCOMMIT_CODEX_ARGS
• CCOMMIT_KILO_CMD, CCOMMIT_KILO_ARGS
• CCOMMIT_QWEN_CMD, CCOMMIT_QWEN_ARGS
• CCOMMIT_GEMINI_CMD, CCOMMIT_GEMINI_ARGS
• CCOMMIT_PROVIDER_TIMEOUT_MS (optional, default 60000)