agit

# Agit Git records code changes. Agit records autonomous agent work. Agit is an open protocol and CLI for tracking, proving, replaying, and safely reverting AI agent actions across code, tools, databases, and infrastructure. Agit is not meant to replace Git. It sits beside Git and records the work that normal Git history does not capture: the intent, agent runtime, tool calls, command output, proof artifacts, risk level, and available rollback path. ## Why AI agents are starting to edit repos, install packages, run migrations, call APIs, deploy services, and touch production systems. Normal commit history only answers: > What files changed? Agit answers: > What autonomous work happened, why did it happen, what tools were used, what proof exists, and can it be reverted? ## Agent-native usage Humans should not need to operate Agit manually most of the time. A human says: > "Cancel that last change." The agent calls: ```sh agit revert latest ``` A human says: > "Before you touch the database, make sure we can go back." The agent calls: ```sh agit plan --intent "delete inactive users" -- psql -c "delete from users where ..." agit guard -- psql -c "delete from users where ..." agit db snapshot --table users --where "status = 'inactive'" "before database cleanup" agit exec --intent "delete inactive users" --allow-risk R3 --db-snapshot db-... -- psql -c "delete from users where status = 'inactive'" ``` ## Quick start For local development: ```sh npm install npm link --workspace packages/cli npm link --workspace packages/mcp agit install codex ``` `agit install codex` installs the Codex skill and registers the `agit-mcp` server. Restart Codex after installing so the new skill and MCP tool server are loaded. ```sh node packages/cli/bin/agit.js init node packages/cli/bin/agit.js checkpoint "before agent work" node packages/cli/bin/agit.js start "multi-step agent work" node packages/cli/bin/agit.js finish node packages/cli/bin/agit.js exec --intent "change README" -- node -e "require('fs').appendFileSync('README.md', '\nhello\n')" node packages/cli/bin/agit.js prove latest node packages/cli/bin/agit.js log node packages/cli/bin/agit.js show latest node packages/cli/bin/agit.js revert latest ``` After packaging, the intended command is: ```sh agit init agit start "multi-step agent work" agit finish agit exec --intent "fix failing tests" -- npm test agit guard -- terraform apply agit plan --intent "delete dummy users" -- psql -c "delete from users where status='inactive'" agit install codex agit provider status package agit db snapshot --table users --where "status = 'inactive'" "before delete" agit exec --intent "delete inactive users" --allow-risk R3 --db-snapshot db-... -- psql -c "delete from users where status='inactive'" agit revert latest --url postgresql:///mydb agit package snapshot "before dependency install" agit package restore latest agit prove latest agit revert latest ``` ## Current prototype scope - Local `.agit/` workspace store. - Agent session records with intent, tool calls, risk, git before/after state, stdout, stderr, and proof metadata. - `exec` wrapper for command/tool calls. - Revert for file changes when the run started from a clean Git worktree. - Package snapshot and restore provider for JavaScript package manifests and lockfiles. - Auto package snapshot for `npm`, `pnpm`, `yarn`, and `bun` mutation commands. - PostgreSQL row snapshot and restore provider for explicit table/WHERE scopes. - Database snapshots can be attached to sessions with `agit exec --db-snapshot <id>` and restored through `agit revert`. - Provider registry and generic provider commands for implemented and planned reversibility providers. - MCP server foundation via `agit-mcp`. - Codex installer for the Agit skill and MCP registration. - Conservative risk classification for common dangerous commands. - Policy gate with `agit guard` and `agit exec --allow-risk`. - Undo planning with `agit plan`. - Nix-style generations for checkpoints, sessions, and reverts. - JSONL action ledger for agent audit history. - Proof summaries with `agit prove`. - Agent blame with `agit blame <file>`. - Cross-agent memory notes with `agit memory`. - Adapter templates for Codex, Claude Code, Hermes, Mercury, OpenClaw, and MCP. ## Non-goals for v0.1 - Agit does not magically recover data that was changed before Agit existed. - Agit does not promise true undo for irreversible actions like sending email, transferring funds, or deploying immutable contracts. - Agit does not replace database backups, snapshots, Git, or human approval. ## Core idea Every agent action should have a reversibility contract: ```txt R0 read-only R1 file-reversible R2 transaction-reversible R3 snapshot-reversible R4 compensating-action only R5 irreversible ``` Agit should make agents ask: "What is the way back?" before taking real action. ## Commands ```sh agit init agit checkpoint <label> agit start <intent> agit finish [current|session-id] agit exec [--intent <text>] [--allow-risk R3] [--db-snapshot <id>] -- <command> [args...] agit risk -- <command> [args...] agit guard -- <command> [args...] agit plan [--intent <text>] -- <command> [args...] agit policy agit install codex-skill [--force] agit install codex-mcp agit install codex [--force] agit provider list agit provider show <provider> agit provider status <provider> agit provider snapshot <provider> [label] agit provider restore <provider> [latest|snapshot-id] agit db status [--url <connection>] agit db snapshot --table <table> [--where <sql>] [--primary-key <column>] [--url <connection>] [label] agit db list agit db restore [latest|snapshot-id] [--url <connection>] agit package status agit package snapshot [label] agit package list agit package restore [latest|snapshot-id] agit proof add [--label <label>] [--file <path>] [--text <text>] agit prove [latest|session-id] agit blame <file> agit generations agit memory list agit memory add [--label <label>] <text> agit log agit show [latest|session-id] agit revert [latest|session-id] [--url <database-connection>] ``` ## MCP Agit ships a minimal stdio MCP server: ```sh agit-mcp ``` Current MCP tools include checkpoint, guard, plan, add proof, prove, revert, blame, provider discovery/status/snapshot/restore, database status/snapshot/restore/list, package status/snapshot/restore/list, and memory add/list. For Codex: ```sh agit install codex-mcp ``` ## Roadmap See [ROADMAP.md](./ROADMAP.md). ## Project Tracking - [VISION.md](./VISION.md): product vision and long-term direction. - [STATUS.md](./STATUS.md): current implementation state and next milestone. - [DECISIONS.md](./DECISIONS.md): durable design decisions.