Skip to content
SomeoneWithOptionsPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

commiter

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.

Agent quick reference

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 add

Contract:

  • stdout carries data only (--suggest prints the message; --json prints one object). stderr carries errors and, only when attached to a terminal, progress.
  • Exit codes classify failures: 2 usage, 3 no changes, 4 config/key, 5 API, 6 git, 7 push failed after commit. See Exit status and output.
  • Pass paths or --staged. Running bare c stages every change in the repository, including untracked files.
  • --edit requires a terminal and fails fast without one. Do not use it from an agent.
  • --message/--message-file need no API key. Keep message files outside the repository.
  • c --help contains the same guidance, so agents can discover it without this README.

Quick Install

curl -fsSL https://go.sanetomore.com/commiter | sh

This 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.

Build from Source

go build -o commiter .

Usage

  1. 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"
      }
    }

    commiter invokes op read directly 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, op is run without one so it cannot block on a sign-in prompt; sign in beforehand or set OP_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_HOME when 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 placeholder your-key-here is treated as unset, allowing environment fallback.

    Set the OpenRouter model used to generate messages. The installer writes openrouter/free into new configs:

    {
      "openrouter": {
        "api_key": "your-key-here",
        "model": "openrouter/free"
      }
    }

    --model overrides the config. There is no built-in default: if neither is set, commiter fails with an error. Reinstalling or upgrading never touches an existing config, so configs created before this option must add model by hand.

  2. Run the tool in your git repository:

    ./commiter

Help

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.

Default behavior

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.

Agent workflow

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.go

Or 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.txt

The 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.

Paths

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.md

Options and examples

All boolean options default to false. Flags also accept --name=value.

--staged

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 --suggest

--suggest

Generate 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.txt

Cannot combine with --dry-run, --edit, --push, --message, or --message-file.

--message <text>, -m <text>

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)" --push

--message-file <path|->

Read 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 --push

--dry-run

Print 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.txt

--edit

Open 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 --push

--push

Run 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 --push

--model <id>

Choose 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 --suggest

--config <path>

Choose 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 --suggest

--json

Print 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>}.

--help, -h

Print the full help page with examples and exit without accessing Git or OpenRouter.

c --help
c -h

--version

Print 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.5

Exit status and output

Exit 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>.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages