git-agent

Commit, PR, release, and repository-search context for AI-assisted Git work.

git-agent gathers Git evidence with typed Go code, runs a bounded OpenAI-compatible tool-calling loop, and keeps model tools read-only. The commit command is the only workflow that writes to Git, and it does that after message generation by handing the final message to git commit.

TL;DR: use commit-msg when you want a grounded commit message on stdout, use commit when you want the same message created as a Git commit, use release-note for release Markdown, and use search when an agent needs fast local implementation context.

Quick Start

# 1. Install the binary
go install github.com/yusing/git-agent/cmd/git-agent@latest

# 2. Generate a commit message from staged changes
git-agent commit-msg

# 3. Or generate and create the commit
git-agent commit

By default, message-generation commands use ChatGPT/Codex auth from ~/.codex/auth.json. OPENAI_API_KEY is the fallback for OpenAI-compatible provider auth when that file is absent.

go install writes to $(go env GOPATH)/bin by default; make sure that directory is on PATH.

Everyday Workflows

Workflow	Command	Output
Staged commit message	git-agent commit-msg	Final commit message on stdout
Amend commit message	git-agent commit-msg --amend	Final amended commit message on stdout
Generate and commit	git-agent commit	Human trace, then Git commit output
Generate and amend	git-agent commit --amend	Human trace, then Git amend output
Squash PR message	git-agent pr-message	Squash merge message on stdout
Release body	git-agent release-note <base> <release>	Release Markdown on stdout
Version bump release body	git-agent release-note patch	Release Markdown for latest tag to HEAD
Agent context search	git-agent search --agent <query...>	Brief results, plus progress URL when indexing
List search indexes	git-agent search --ls	Local index summaries for the current project
List indexed files	git-agent search --ls-files	Tree of files stored in the selected index

Why git-agent?

LLMs are useful for Git writing, but raw prompts miss repository facts easily: staged scope, amend intent, recent message style, generated-heavy diffs, submodule history, guidance files, release ranges, and stdout/stderr contracts.

git-agent front-loads those facts before the model writes:

1. It inspects the repository with typed Git plumbing.
2. It builds task-specific evidence for commit, PR, release, or search work.
3. It exposes only narrow read-only tools when the model needs more context.
4. It validates and shapes final output for the requested workflow.

For submodule-only staged updates, normal commit-msg and commit skip the LLM entirely and format a deterministic local message.

What It Provides

Surface	What it does
Prepared Git context	Staged paths, status, stats, diffs, amend base, branch diffs, release ranges, and recent style commits
Read-only model tools	Bounded file, diff, and repository inspection tools for generation workflows
Guidance discovery	AGENTS/CLAUDE-family project instructions, plus local Codex-style SKILL.md workflow guidance
Commit execution	Optional explicit git commit --file - or git commit --amend --file - after message generation
Release-note writing	Release Markdown from explicit refs or patch, minor, and major shortcuts
Embedding search	Local filesystem or committed-tree context search for agents and humans
Trace artifacts	JSON request/response/tool-call traces for message generation commands
Debug output	Human console diagnostics with --debug; pprof with --pprof <addr>

Search

git-agent search is embedding-backed implementation-location search. It does not run the Responses API or create message-generation sessions.

# Search current filesystem files; Git repositories share a root index
git-agent search "where is release note evidence prepared"

# Compact output for humans
git-agent search --format brief "where are search flags parsed"

# Agent mode: compact output plus progress probe when indexing
git-agent search --agent "where are search flags parsed"

# Search code only, excluding common tests
git-agent search --code --no-tests "commit amend validation"

# Index first, without running a query
git-agent search --index

# Search a committed tree instead of the working filesystem
git-agent search --rev HEAD~1 "guidance discovery"

# Search a cached remote repository
git-agent search --remote https://github.com/yusing/git-agent.git "search flags"

# List search indexes for this project
git-agent search --ls

# List cached remote repositories
git-agent search --ls-remotes

# List indexed files as a tree
git-agent search --ls-files

Search reads OPENAI_EMBEDDING_API_KEY first, then falls back to OPENAI_API_KEY. Codex/ChatGPT auth is not used for embeddings. Use OPENAI_EMBEDDING_BASE_URL, OPENAI_EMBEDDING_MODEL, and OPENAI_EMBEDDING_DIMENSIONS to isolate search embedding config from normal message-generation config.

Normal indexing reuses exact matching chunk embeddings from compatible indexes for the same project or cached remote. This includes filesystem-to-revision and revision-to-revision reuse, so searching a nearby commit usually embeds only its changed chunks. Compatible indexes also reference one shared on-disk vector payload per project or remote cache instead of copying unchanged vectors into every snapshot. Existing local vector payloads migrate on a later cache write. --reindex skips cross-index reuse, rebuilds the selected source, and appends a new shared vector generation without changing older snapshots.

Useful flags:

Flag	Purpose
--scope <paths>	Limit search or indexing; local paths are current-directory-relative, remote paths are repository-relative
--rev <rev>	Search a committed Git tree
--remote <url>	Search a cached remote Git repository URL
--code	Include source-code files only
--no-tests	Exclude common cross-language test filenames and test directories from results and --ls-files output
--min-relatedness <n>	Set vector relatedness candidate threshold
--limit <n>	Limit result count
--format	Use json|brief for search, text|json for --ls, text|json|completion for --ls-remotes, and tree|json for --ls-files
--index	Build missing embeddings without searching
--reindex	Rebuild existing embeddings and drop stale cache entries
--agent	Use agent-friendly brief output and serve indexing progress on localhost when embeddings need work
--ls	List search indexes for the current project or --remote cache without embedding or querying
--ls-remotes	List cached remote repositories without embedding, fetching, or querying
--ls-files	List files in the selected search index without embedding or querying; --no-tests filters listed paths without changing the selected index

Index inspection commands:

git-agent search --ls
git-agent search --ls --format json
git-agent search --ls-remotes
git-agent search --ls-remotes --format json
git-agent search --ls-remotes --format completion
git-agent search --ls-files
git-agent search --ls-files --format json
git-agent search --ls-files --no-tests
git-agent search --ls-files --rev HEAD --scope internal/
git-agent search --ls-files --remote https://github.com/yusing/git-agent.git

Use docs/spec.md for exact cache layout and index-selection contracts.

See git-agent search --help and docs/spec.md for exact output, cache, ignore-file, and debug behavior.

CLI Reference

Everyday commands:

git-agent commit-msg [--amend] [flags]
git-agent commit [--amend] [flags]
git-agent pr-message [flags]
git-agent release-note [--out <file>] [flags] <base> <release>
git-agent release-note [--out <file>] [flags] patch|minor|major
git-agent search [flags] <query...>
git-agent search --ls [--remote <url>] [--format text|json]
git-agent search --ls-remotes [--format text|json|completion]
git-agent search --ls-files [--format tree|json] [--remote <url>] [--rev <rev>] [--scope <paths>] [--no-tests]

Common message-generation flags:

Flag	Purpose
--model <name>	Override OPENAI_MODEL
--fast	Request fast service tier
--low, --medium, --high, --xhigh	Set reasoning effort
--base-url <url>	Override provider base URL
--timeout <duration>	Override request timeout
--max-steps <n>	Bound agent loop steps
--guidance-family auto|agents|claude|codex|none	Force guidance family
--append-prompt <text>	Add a bounded operator hint
--debug	Print diagnostics and trace location
--pprof <addr>	Serve Go pprof endpoints

release-note --out <file> writes the rendered Markdown to the file, streams a human console trace to stdout, and skips the on-disk JSON trace session.

Configuration

Default auth comes from:

~/.codex/auth.json

The file must include ChatGPT auth:

{
  "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>. Requests also identify the Codex client by sending originator: codex_cli_rs and User-Agent: codex_cli_rs.

When ~/.codex/auth.json is absent, OPENAI_API_KEY is used as a legacy OpenAI-compatible fallback. OPENAI_BASE_URL only applies to that fallback path unless --base-url is passed explicitly.

Supported environment variables:

Variable	Used for
OPENAI_API_KEY	Message-generation fallback auth and search fallback auth
OPENAI_BASE_URL	Message-generation fallback base URL and search fallback base URL
OPENAI_MODEL	Message-generation model; defaults to gpt-5.6-luna
OPENAI_EMBEDDING_API_KEY	Search embedding auth
OPENAI_EMBEDDING_BASE_URL	Search embedding base URL
OPENAI_EMBEDDING_MODEL	Search embedding model
OPENAI_EMBEDDING_DIMENSIONS	Search embedding dimensions
OPENAI_EMBEDDING_MAX_INPUT_CHARS	Search per-input character cap
OPENAI_EMBEDDING_BATCH_INPUTS	Search embedding request input count
OPENAI_EMBEDDING_BATCH_MAX_CHARS	Search embedding request character budget
OPENAI_EMBEDDING_CONCURRENCY	Search embedding request concurrency

CLI flags override environment values.

With ChatGPT auth, the gpt-5.6 alias resolves to gpt-5.6-sol. The canonical gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna identifiers pass through unchanged.

Behavior defaults:

• service_tier is omitted unless --fast is set.
• Reasoning effort is omitted unless --low, --medium, --high, or --xhigh is set.
• --append-prompt can steer style or emphasis only when consistent with the task contract and repository evidence.

How It Works

flowchart TD
    Start["git-agent command"] --> Inspect["Typed Git inspection"]
    Inspect --> Context["Prepared task context"]
    Context --> Guidance["Project guidance and skills"]
    Guidance --> Agent["Bounded read-only agent loop"]
    Agent --> Validate["Validate and shape output"]
    Validate --> Output["stdout, file, or git commit"]
    Inspect --> Search["search: embed and rank local chunks"]
    Search --> SearchOutput["JSON or brief stdout"]

Loading

Message-generation commands write JSON traces 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.

Search indexes use the same project metadata root:

~/.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.

Local Development

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

make install installs the locally built binary and honors DESTDIR for package-style installs.

Fish completion install defaults:

Variable	Default
XDG_CONFIG_HOME	$(HOME)/.config
FISH_CONFIG_DIR	$(XDG_CONFIG_HOME)/fish
FISH_COMPLETIONS_DIR	$(FISH_CONFIG_DIR)/completions

Security and Privacy

• Model tools are read-only and bounded.
• No arbitrary shell command tool is exposed to the model.
• commit and commit --amend are explicit Git write commands, run only after message generation.
• Normal Git config, hooks, signing, and gpg-agent behavior apply when creating commits.
• Message generation sends prepared repository context to the configured provider.
• Search sends indexed chunks and queries to the configured embedding provider.
• API keys and bearer tokens are redacted from traces, debug output, and errors.

Specification

docs/spec.md is the normative behavior contract for commands, flags, stdout/stderr, tracing, search indexing, guidance discovery, and model tool limits. Keep README changes user-facing; update the spec when behavior or contracts change.