git-agent

git-agent is an OpenAI-compatible tool-calling agent harness for Git-related operations. Model tools are read-only; the explicit commit command can run the final Git commit after message generation.

Commands

• git-agent commit-msg
• git-agent commit-msg --amend
• git-agent commit
• git-agent commit --amend
• git-agent pr-message
• git-agent release-note [--out <file>] <base> <release>
• git-agent release-note [--out <file>] patch|minor|major
• git-agent search [flags] <query...>

Configuration

By default, git-agent uses ChatGPT/Codex auth from:

~/.codex/auth.json

The auth file must include:

{
  "auth_mode": "chatgpt",
  "tokens": {
    "access_token": "...",
    "account_id": "..."
  }
}

ChatGPT auth sends requests to https://chatgpt.com/backend-api/codex with Authorization: Bearer <access_token> and ChatGPT-Account-ID: <account_id>.

OPENAI_API_KEY is a legacy fallback when ~/.codex/auth.json is absent. OPENAI_BASE_URL only applies to that legacy API-key path; ChatGPT auth uses the ChatGPT backend unless --base-url is passed explicitly. Supported environment variables:

• OPENAI_API_KEY
• OPENAI_BASE_URL
• OPENAI_MODEL
• OPENAI_EMBEDDING_API_KEY
• OPENAI_EMBEDDING_BASE_URL
• OPENAI_EMBEDDING_MODEL
• OPENAI_EMBEDDING_DIMENSIONS
• OPENAI_EMBEDDING_MAX_INPUT_CHARS
• OPENAI_EMBEDDING_BATCH_INPUTS
• OPENAI_EMBEDDING_BATCH_MAX_CHARS
• OPENAI_EMBEDDING_CONCURRENCY

CLI flags override environment values.

Common flags:

• --model
• --fast
• --low
• --medium
• --high
• --xhigh
• --base-url
• --timeout
• --max-steps
• --guidance-family
• --append-prompt
• --debug
• --pprof <addr>

search is embeddings-only semantic retrieval for agents. It searches the current filesystem by default, or a committed tree with --rev <rev>, and writes JSON results to stdout by default. Use --format brief for compact line-oriented results. Use --code to limit candidates to source-code files by extension. The code filter does not exclude tests by name, and filesystem mode still includes staged, unstaged, and untracked files when they are present under the search root and not ignored or skipped. Generated Go files with a pre-package DO NOT EDIT heading are included as path-only chunks so generated body content is not embedded. Use --scope foo,bar/baz to limit search or indexing to comma-separated root-relative paths. Use --no-tests to exclude common test files and test directories. Use --index without a query to build or refresh missing embeddings without searching; add --reindex to rebuild existing embeddings too. Search uses OPENAI_EMBEDDING_API_KEY when set, then falls back to OPENAI_API_KEY; Codex/ChatGPT auth is not used for embeddings. Successful indexing writes the local cache after embedding completes. See docs/spec.md for exact output, file discovery, ignore-file, skip, cache, and debug behavior; run git-agent search --help for the current search flag list.

Behavior defaults:

• omit service_tier unless --fast is set
• omit reasoning mode unless one of --low, --medium, --high, or --xhigh is set
• --append-prompt adds a bounded operator hint to the task prompt; it can steer style or emphasis only when consistent with the task contract and repository evidence

Build and install

make build
make test
make install PREFIX=/usr/local

make install also honors DESTDIR for package-style installs.

If $(FISH_CONFIG_DIR) exists, make install also installs fish completions to $(FISH_COMPLETIONS_DIR)/git-agent.fish. Defaults:

• XDG_CONFIG_HOME ?= $(HOME)/.config
• FISH_CONFIG_DIR ?= $(XDG_CONFIG_HOME)/fish
• FISH_COMPLETIONS_DIR ?= $(FISH_CONFIG_DIR)/completions

Debug sessions

Message-generation commands store a JSON trace under:

~/.git-agent/<path-sha>/sessions/<timestamp>-<command>/

Trace files include session metadata, provider requests/responses, tool calls, and returned tool output. API keys are redacted. --debug prints the trace directory to stderr.

The <path-sha> component is the SHA-256 of the cleaned absolute project root. Search indexes use the same project metadata root under ~/.git-agent/<path-sha>/search/. On the next run for an existing project, legacy metadata from <project>/.git-agent/ is migrated into the home metadata directory automatically.

--pprof <addr> serves Go pprof endpoints on the requested address, for example :7777.

release-note --out <file> writes the rendered Markdown to the requested file and skips the on-disk JSON trace session. release-note patch|minor|major finds the latest reachable semantic version tag, bumps the requested component, and uses HEAD as the release revision.

commit and commit --amend generate the same message as commit-msg, stream the human console trace to stdout, then run git commit --file - or git commit --amend --file -. Normal Git config, hooks, signing, and gpg-agent behavior apply. If commit creation fails after message generation, the command exits nonzero and includes both the generated message and Git error. In amend mode, the current HEAD message is treated as the message anchor so small staged refinements preserve the original subject.

For normal non-amend commits where the staged changes are only submodule gitlink updates, commit-msg and commit format the message locally without an LLM call or provider auth.