git-agent

Agent-native layer on top of git for checkpoint-based development.

Overview

git-agent is a CLI tool that provides checkpoint-based development workflows for AI agents. It maintains a shadow history in .agent/ that tracks every state change, which can later be compiled into clean git commits.

Key concepts:

• Session: A development session with a clear goal and base commit
• Checkpoint: An immutable snapshot of work (references git tree objects)
• Intent: The "why" behind changes (goals, assumptions, acceptance criteria)

Installation

cargo install --path .

Or with nix:

nix-shell --run "cargo build --release"

Usage

# Initialize in a git repository
git-agent init

# Start a development session with a clear goal
git-agent begin "Fix N+1 query in PostsController#index"

# Create checkpoints that capture what you tried and why
git-agent checkpoint -m "Tried eager loading - breaks pagination"
git-agent checkpoint -m "Switched to batch loading (includes), pagination works"
git-agent checkpoint -m "Added index on posts.user_id for the batch query"

# Check current status
git-agent status

# View checkpoint history
git-agent log

# Undo to previous checkpoint (restores files)
git-agent undo        # Undo last checkpoint
git-agent undo 2      # Undo last 2 checkpoints

# Compile checkpoints into commits (not yet implemented)
git-agent compile
git-agent squash

Commands

Command	Description
init	Initialize .agent/ directory
begin	Start a new development session
checkpoint	Create a checkpoint of current state
status	Show current session status
log	Show checkpoint history
undo	Restore working directory to a previous checkpoint
compile	Generate commit plan from checkpoints (not yet implemented)
squash	Execute commit plan (not yet implemented)
pr	Generate PR description (not yet implemented)
sync	Reconcile after raw git commands (not yet implemented)
abandon	Abandon current session (not yet implemented)

Output Formats

All commands support JSON output with the --json flag:

git-agent status --json

Human-readable output is the default.

Storage

git-agent stores its state in .agent/ alongside .git/. This directory is automatically added to .git/info/exclude to avoid polluting the repository.

.agent/
├── VERSION
├── config.toml
├── current               # Current session ID
└── sessions/
    └── <session-id>/
        ├── session.json  # Session metadata
        ├── intent.json   # Intent/goal metadata
        └── checkpoints/
            ├── 0001.json  # Checkpoint metadata
            ├── 0001.patch # Unified diff
            └── ...

Writing Good Checkpoint Messages

Checkpoints should capture what you tried and why, not just what changed. This makes the history useful for review and debugging.

Bad messages (what changed):

git-agent checkpoint -m "Updated query"
git-agent checkpoint -m "Fixed bug"
git-agent checkpoint -m "Added tests"
git-agent checkpoint -m "Refactored code"

Good messages (what you tried and why):

git-agent checkpoint -m "Tried raw SQL - faster but bypasses model validations"
git-agent checkpoint -m "Used find_each instead of all.each - memory stays flat"
git-agent checkpoint -m "Extracted service object - controller was 400 lines"
git-agent checkpoint -m "Reverted memoization - cache invalidation was broken"
git-agent checkpoint -m "Added retry with backoff - external API flaky under load"
git-agent checkpoint -m "Switched from redis to postgres advisory locks - one less dependency"

The goal: someone reading git-agent log should understand your reasoning without looking at the diff.

Design Philosophy

This tool was designed through a debate between multiple AI models (Claude, Codex, Gemini, Ollama) about what an agent-native version control layer should look like. Key design decisions:

1. Layer on git, not replace it: Use git's content-addressed storage while providing agent-friendly interfaces
2. Checkpoints are immutable: Append-only history for safety
3. Intent is first-class: Track the "why" alongside the "what"
4. JSON output for agents: Machine-readable by default
5. No daemon: Stateless CLI that reads/writes files
6. Git compatibility: Never breaks raw git usage

License

MIT