npm package: @sabinm677/ccommit
Description: AI-powered Git commit message generator with Conventional Commits output.
Author: Sabin Maharjan
Latest version: 0.2.1

# 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
```bash
ccommit
# or from repo root
bin/ccommit
```

## Installation

### Via npm (recommended)
```bash
npm install -g @sabinm677/ccommit
```

### From source
```bash
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):
```bash
ccommit --show
ccommit -s
```

Override generated first line:
```bash
ccommit -m "ABC-1: Some message"
ccommit --message "ABC-1: Some message"
```

Choose provider for one run:
```bash
ccommit --provider opencode
ccommit -p codex
ccommit -p kilo
ccommit -p qwen
ccommit -p gemini
```

Persist a default provider:
```bash
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:
```text
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):
```text
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`

```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:
```bash
bun test
```

Build standalone executables:
```bash
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`)