A Go CLI tool that automates the git commit process. It stages all changes, generates a clean, plain-text commit message using the OpenRouter API, and commits the changes. Agents can also generate a suggestion, review or extend it, then commit the supplied message without opening an editor.
c --version # confirm available options
c --json --suggest -- src/main.go # generate message; nothing committed
c --json -m "fix(auth): refresh tokens" -- src/main.go # commit selected files
c --json --dry-run -- src/main.go # preview diff + message, no commit
c --json --staged -m "docs: update readme" # commit what you staged with git addContract:
- stdout carries data only (
--suggestprints the message;--jsonprints one object). stderr carries errors and, only when attached to a terminal, progress. - Exit codes classify failures:
2usage,3no changes,4config/key,5API,6git,7push failed after commit. See Exit status and output. - Pass paths or
--staged. Running barecstages every change in the repository, including untracked files. --editrequires a terminal and fails fast without one. Do not use it from an agent.--message/--message-fileneed no API key. Keep message files outside the repository.c --helpcontains the same guidance, so agents can discover it without this README.
curl -fsSL https://go.sanetomore.com/commiter | shThis downloads the latest release binary to ~/.local/bin/c and creates a private config containing a placeholder credential and the openrouter/free model. Existing config is never overwritten.
go build -o commiter .-
Configure your OpenRouter API key in the file created by the installer:
${EDITOR:-vi} ~/.config/commiter/config.json
For a Linux source install, create it first with:
mkdir -p ~/.config/commiter touch ~/.config/commiter/config.json chmod 600 ~/.config/commiter/config.json
To read the key directly from 1Password, install and sign in to the 1Password CLI, then use a secret reference:
{ "openrouter": { "api_key": "op://Private/OpenRouter/personal" } }commiterinvokesop readdirectly without a shell, so shell commands and substitutions in the config are never executed. The referenced field must contain only the OpenRouter API key. When stdin is not a terminal,opis run without one so it cannot block on a sign-in prompt; sign in beforehand or setOP_SERVICE_ACCOUNT_TOKEN.A literal API key is also supported:
{ "openrouter": { "api_key": "your-key-here" } }On Linux, the default config directory follows
$XDG_CONFIG_HOMEwhen set. On macOS and Windows, the platform user config directory is used. Config files with group or other permissions are rejected on Unix.Alternatively, keep using the environment variable when no key is configured:
export OPENROUTER_API_KEY="your-key-here"
Config takes precedence over
OPENROUTER_API_KEY. The installer placeholderyour-key-hereis treated as unset, allowing environment fallback.Set the OpenRouter model used to generate messages. The installer writes
openrouter/freeinto new configs:{ "openrouter": { "api_key": "your-key-here", "model": "openrouter/free" } }--modeloverrides the config. There is no built-in default: if neither is set,commiterfails with an error. Reinstalling or upgrading never touches an existing config, so configs created before this option must addmodelby hand. -
Run the tool in your git repository:
./commiter
Run c --help or c -h for a brief description of every option. Help works outside a Git repository and does not require an API key. The examples below use the installed c command; replace it with ./commiter for a source build.
c stages all changes throughout the repository, including untracked files, generates a Conventional Commits subject with OpenRouter, then commits. Pass paths to limit staging to specific files. It does not push unless --push is supplied. If staging, generation, or committing fails, it attempts to restore the original staged changes.
Pass the files you intend to commit as paths, generate a suggestion, review or edit it, then commit it with --message (or --message-file for longer bodies):
c --suggest -- src/main.go
# fix(auth): refresh expired tokens before retrying
c -m "fix(auth): refresh expired tokens before retrying" -- src/main.goOr stage files yourself with git add and use --staged:
git add src/main.go
c --staged --suggest
c --staged -m "fix(auth): refresh expired tokens before retrying"For a multi-paragraph body, write the message to a file outside the repository and let the agent read and edit that file:
c --staged --suggest > /tmp/commit-message.txt
# Read/edit /tmp/commit-message.txt, then commit it:
c --staged --message-file /tmp/commit-message.txtThe message can include a body after a blank line:
fix(auth): refresh expired tokens before retrying
Preserve request body when retrying authenticated uploads.
Verified with auth integration tests.
Keep staged changes unchanged between generation and commit. If they change, review the diff and message again. Keep message files outside the repository so that staging all changes does not accidentally include them.
Positional arguments are Git pathspecs. When given, only matching files are staged (additions, modifications, and deletions, via git add --all -- <paths>) and committed; everything else stays untouched. Put options before paths, and use -- to separate them when a path could look like an option.
Before staging, c verifies that the index holds no staged changes outside the given paths. If it does, the command fails with exit 6 and lists the offending files, so a path-limited commit never silently includes unrelated staged work. Commit or unstage those files first (git restore --staged -- <file>), or run without paths.
Paths work with generation, --suggest, --dry-run, --message, --message-file, and --push. They cannot combine with --staged. If any step fails, the original staged state is restored.
c -- src/main.go src/auth/
c --suggest -- src/main.go
c -m "docs: update readme" README.mdAll boolean options default to false. Flags also accept --name=value.
Use only changes already staged with git add. Unstaged changes and untracked files are left alone. Works with generation, previews, supplied messages, editing, and pushing. Cannot combine with paths.
git add src/main.go
c --staged
c --staged --suggestGenerate a suggestion and print only the message, followed by a newline, to stdout. No commit, push, editor, or spinner. Errors go to stderr. Generation still requires an OpenRouter API key.
Without --staged, all changes are temporarily staged to generate the diff, then the original staging is restored before generation. With --staged, no temporary staging is needed.
c --suggest
c --staged --suggest > /tmp/commit-message.txtCannot combine with --dry-run, --edit, --push, --message, or --message-file.
Commit the supplied message. Skip AI generation and config loading, so no API key is required. Multiline messages and letter case are preserved, subject to Git's normal message cleanup. Empty or NUL-containing messages fail before staging changes. No editor or spinner opens.
By default, stage and commit all changes. Add --staged to commit only staged changes, --dry-run to preview, or --push to push after committing. Cannot combine with --message-file or --edit.
c --staged -m "fix(auth): refresh expired tokens before retrying"
c -m "$(c --suggest)" --pushRead the final message from a file, or use - to read stdin. Skip AI generation and config loading, so no API key is required. Multiline bodies and letter case are preserved, subject to Git's normal message cleanup. Empty, unreadable, or NUL-containing messages fail before staging changes. No editor or spinner opens.
By default, stage and commit all changes. Add --staged to commit only staged changes, --dry-run to preview the diff and supplied message, or --push to push after committing. Cannot combine with --message or --edit; edit the file first.
c --staged --message-file /tmp/commit-message.txt
c --staged --message-file - < /tmp/commit-message.txt
c --message-file /tmp/commit-message.txt --pushPrint the diff and message without committing or pushing. Without --staged, temporarily stage all changes for the preview, then restore the original staging. With --message-file, preview the supplied message without an API call. --edit and --push are ignored during a dry run.
This output includes headings and the diff; use --suggest when you need only the generated message.
c --dry-run
c --staged --dry-run
c --staged --dry-run --message-file /tmp/commit-message.txtOpen Git's configured editor to review or change the generated message before committing. Git selects the editor using GIT_EDITOR, core.editor, VISUAL, or EDITOR. Requires an interactive terminal on stdin; when stdin is a pipe or file (agents, CI), the command fails with exit 2 before touching Git instead of hanging in an editor. If editing or committing fails, the tool attempts to restore original staging when it staged changes itself. Agents should use --suggest followed by --message-file.
c --edit
c --staged --edit --pushRun git push after a successful commit, using Git's configured remote and upstream. If pushing fails, the local commit remains; retry with git push after addressing the failure.
c --push
c --staged --message-file /tmp/commit-message.txt --pushChoose the OpenRouter model for generation. Overrides openrouter.model from the config. Fails if neither is set. Ignored when using --message or --message-file.
c --model "openrouter/free" --staged --suggestChoose a different JSON config file for the API key and model. By default, use commiter/config.json inside the platform user config directory: on Linux, $XDG_CONFIG_HOME/commiter/config.json when set, otherwise ~/.config/commiter/config.json.
Config credentials take precedence over OPENROUTER_API_KEY; empty or placeholder credentials fall back to the environment. An explicitly supplied missing or invalid config fails. Unix config files must have private permissions (chmod 600). Literal keys and op:// 1Password references are supported, as described above. Ignored when using --message or --message-file.
c --config ~/.config/commiter/work.json --staged --suggestPrint the outcome as a single JSON object on stdout instead of text. Works with every mode, including --version. When the command fails, the error is printed as JSON on stderr and the exit code is unchanged.
c --json --suggest -- src/main.go
# {"mode":"suggest","message":"fix(auth): refresh expired tokens","files":["src/main.go"],"model":"openrouter/free","diff_truncated":false,"pushed":false}
c --json -m "fix(auth): refresh expired tokens" -- src/main.go
# {"mode":"commit","message":"fix(auth): refresh expired tokens","files":["src/main.go"],"diff_truncated":false,"commit":"3f2a9c1b...","short_commit":"3f2a9c1","branch":"main","pushed":false}
c --json --dry-run # adds "diff":"..."
c --json --version # {"version":"v1.4.0","revision":"...","os":"linux","arch":"amd64","go":"go1.25.5"}Fields:
| Field | Meaning |
|---|---|
mode |
suggest, dry-run, or commit |
message |
Generated or supplied commit message |
files |
Files that were (or would be) committed |
diff |
Staged diff; dry-run only |
model |
OpenRouter model used; omitted for supplied messages |
diff_truncated |
true when the diff was cut to fit the model prompt |
commit, short_commit, branch |
Set after a successful commit |
pushed |
true when --push succeeded |
Error shape: {"error":"<message>","code":"usage|no_changes|config|api|git|push|failure","exit_code":<n>}.
Print the full help page with examples and exit without accessing Git or OpenRouter.
c --help
c -hPrint the version, build revision, platform, and Go version, then exit. Release binaries report their tag; source builds report dev plus the VCS revision. Works outside a Git repository and needs no API key. Agents can use it to confirm which options are available.
c --version
# commiter v1.4.0 (3f2a9c1b8d4e) linux/amd64 go1.25.5Exit codes identify the failure class so scripts and agents can branch without parsing text:
| Code | Meaning |
|---|---|
0 |
Success, help, or version |
1 |
Unclassified error |
2 |
Invalid options, or an empty/unreadable supplied message |
3 |
No changes to commit |
4 |
Config, API key, or model missing or invalid |
5 |
OpenRouter request failed |
6 |
Git operation failed (not a repository, staging, diff, commit, restore) |
7 |
Commit succeeded but git push failed; the local commit remains |
Errors and progress go to stderr. The progress spinner is shown only when stderr is a terminal; when stderr is a pipe or file, no progress or control characters are written. --suggest writes only its message to stdout; regular commits print the message followed by Committed <short-sha> on <branch>. (or ... and pushed.), so callers can verify the result with git show <sha>.