0.1.0 Rust · MIT or Apache-2.0 · single binary

git's workflow.
Re-engineered for agents.

git was designed for a human who makes a handful of commits a day and reads prose. AI agents make thousands of tiny changes in parallel, crash mid-operation, retry blindly and have to coordinate without anyone watching. agit keeps init, add, commit, branch, merge, push and pull, and rebuilds everything underneath for that world.

JSON on every command Compare-and-swap refs Leases, checkpoints, events Server with PRs and policies

    
Why agit, not git

git is the best developer tool of the last twenty years. Used by a fleet of agents, it fails in ten specific, repeatable ways.

Each failure below is something agit addresses directly, not by wrapping git. Everything marked built ships in 0.1.0 today.

Output you have to parse built

git: status, log, diff and every error are prose. Agents write regexes that break on locale, version and porcelain changes. Exit codes do not say whether a retry makes sense.

agit: every command takes --json and prints one envelope, {"ok":true,"result":…} or {"ok":false,"error":{code,message,retryable,details}}. Exit codes are classes: 0 ok, 1 error, 3 conflict, 75 retryable. Branch on error.code, never on text.

Stale lock files built

git: kill a process at the wrong moment and index.lock or refs/heads/main.lock stays behind. Every later command fails until a human deletes the file. With ten agents this happens hourly.

agit: advisory flock on .agit/locks/*. The kernel releases the lock when the process dies, however it dies. Writes are temp file + fsync + rename. There is nothing to clean up, ever.

Conflicts discovered after the budget is spent built

git: two agents are told to work in src/auth. Both spend twenty minutes and a few dollars of tokens. The merge fails. git has no primitive for "I am working here for the next thirty minutes".

agit: leases: time-limited, glob-based claims on paths. The second agent learns in milliseconds with lease_conflict, before writing a line, and its commit into the leased paths is refused unless forced. Leases expire on their own, so a crashed agent never blocks anyone for long.

Last writer wins on refs built

git: concurrent pushes to a shared branch are a race; compare-and-swap means update-ref with an old value and hoping nobody uses porcelain.

agit: every ref update, local or remote, states what it expects (an id, absent, or any). A concurrent move fails with ref_conflict, which is retryable: true: re-read, reconcile, retry. Several refs move in one atomic transaction.

The commit message is the only metadata built

git: why a change was made, which ticket, which agent and model produced it, on whose behalf: free text or nowhere.

agit: structured commit fields intent, task, agent{id, model, run_id, on_behalf_of}, meta, plus an optional Ed25519 signature with the public key inside the commit. agit log --agent coder-2 and --task PROJ-123 answer provenance questions with no external database.

No cheap snapshots built

git: an agent wants to snapshot before every risky edit. That means WIP commits that pollute history or stash gymnastics that lose untracked files.

agit: checkpoints snapshot the whole working tree, untracked files included, onto refs/checkpoints/<workspace>. They never appear in branch history, cost one tree walk, and agit restore puts everything back.

Polling to notice each other built

git: agents run git log and git status in loops to see what the others did.

agit: every state change appends one line to events.jsonl with a sequence number: commits, ref moves, leases, workspaces, merges. agit events --follow tails it; the server exposes the same stream over SSE and signed webhooks.

Heavy worktrees built

git: one agent per worktree is the right model, but git worktree is an afterthought with its own failure modes.

agit: workspaces: agit ws new coder-2 creates a working directory on its own branch ws/coder-2, sharing objects, refs, leases and events. A crashed agent's workspace is removed without touching anyone else's state.

Knowledge lives outside the repository built

git: design decisions, gotchas and specs sit in wikis and chat logs. The agent editing the code never sees them.

agit: notes with typed tags next to the code, rules that map paths to tags, staleness when the covered paths change, a draft note from every merged pull request, and agit know context <path>: what to read before touching a path, in one call.

SHA-1 and slow status built

git: SHA-1 is collision-broken and slow; the SHA-256 mode is still not the default. status re-stats and often re-hashes everything, and agents call it far more often than humans.

agit: BLAKE3 ids with a kind tag inside the hash, multi-threaded above 128 KiB. Tree entries carry file sizes so listings never open blobs; a stat cache and cached directory tree ids make a commit cost time proportional to the change.

The advantages, measured

Fewer round trips, no cleanup, and numbers from a real laptop.

Measured on 2026-10-15 on an Apple Silicon MacBook Pro against git 2.x, a 2,000-file tree, one process per command for both tools. Only measured numbers appear here; everything else is a target in the roadmap.

12.5 msadd + commit of one file (git: 34.6 ms)
3.4 mslog -n 20 (git: 12.7 ms)
11.1 msstatus on a clean tree (git: 15.3 ms)
0lock files to delete after a crash
1 callfor notes, history, leases and open PRs of a path
33MCP tools with the same JSON as the CLI

The machine contract

One shape for success, one for failure, on every command, in the HTTP API, in the MCP server and in both SDKs. Codes are stable; messages are for humans.

# success
{"ok":true,"result":{"id":"edf2c5ac…","tree":"560556cb…","parents":["44b9a0f2…"],
 "branch":"feature/config","summary":"Load the greeting from Config"}}

# failure: a code, a flag, structured details, exit 75
{"ok":false,"error":{"code":"ref_conflict","retryable":true,
 "message":"reference refs/heads/main changed concurrently",
 "details":{"name":"refs/heads/main","expected":"7f3c…","actual":"9d2e…"}}}

Exit codes an agent can act on

ExitMeaningExamples
0success
1error, do not repeat as ispolicy_violation, nothing_to_commit, invalid
3conflict, needs a decisionmerge_conflicts, lease_conflict, dirty_worktree
75transient, retry after re-readingref_conflict, lock_timeout
Side by side

Same vocabulary, different machinery.

A frank comparison. built ships today, planned is designed in the RFCs but not implemented.

Capabilitygitagit
Commandsinit / add / commit / branch / merge / push / pullthe same, plus lease, ws, checkpoint, events, pr, know, key, mcp
Machine outputporcelain formats, prose errors, ambiguous exit codes--json everywhere, stable error.code, retryable, exit classes 0/1/3/75 built
HashSHA-1 (SHA-256 optional, not default)BLAKE3-256, kind tag inside the hash, parallel above 128 KiB built
Object encodingzlib, text headers, delta-compressed packfileszstd, binary trees with sizes, JSON commits, append-only pack segments; no delta compression yet built
Verificationon fsck and some readsevery read re-hashes; index and segment indexes checksummed built
Locking.lock sentinel files that outlive crashesadvisory flock, nothing to clean up built
Ref updateslast writer wins unless scriptedcompare-and-swap always, multi-ref transactions, server CAS at the log head built
Work claimingnoneleases with TTL, globs, commit-time enforcement, lease board built
Multiple working dirsgit worktreeworkspaces on ws/<name>, shared store, leases and events built
Cheap snapshotsstash, WIP commitscheckpoints outside history, untracked files included built
Commit metadatamessage, author, committer, GPG/SSH signatureplus intent, task, agent{id, model, run_id, on_behalf_of}, meta; Ed25519 signature with the key in the commit built
Change notificationnone (poll)event log with seq, --follow, SSE, signed webhooks built
History toolslog, blame, bisect, rebase, filter-branch, LFSlog with agent/task/path filters and graph, blame, revert, cherry-pick, stash, grep, reflog, reset, gc, submodules built; rebase, bisect planned
HostingSaaS or a large self-hosted stackone static binary, one data directory, reverse proxy for TLS built
Pull requestsfree-text comments, review states, checkstyped PR with intent and task, comments with a kind, reviews, checks, mergeability preview, server-side merge with CAS built
Branch protectionplatform rulesprotected branches, PR-only, approvals, blockers, required checks, required intent/agent/signature, allowed agents, max files per commit built
Agent identitya bot userfirst-class agent{id, model, run_id} on commits, PRs, reviews and notes; scoped tokens bound to an agent; key registry; audit log built
Knowledgewiki, issues, chattyped notes linked to paths/commits/PRs, tag rules, BM25 search, staleness, drafts from merges, context packs, offline store built
Agent toolingshell out and parseMCP server (33 tools), Claude Code hooks, Python and TypeScript SDKs built
Very large repositoriesdelta compression, LFS, partial clone, sparse checkoutcontent addressing, dedup, zstd, sizes in trees, want/have transfer built; blob tiers, chunked large objects, partial clone, sharding planned (details)
Replicationplatform managedsingle node today; Raft log, sharding planned
Maturity20 years, every tool knows it0.1.0, pre-format-freeze; git bridge for import/export built

Where agit is better today

  • Agents that must act without a human in the loop: structured errors, CAS refs, leases, checkpoints and events remove the guessing and the cleanup.
  • Many small commits by many parallel workers in one repository (workspaces plus leases).
  • Review and merge automation: typed comments, policies that say exactly why a merge was refused, server-side merge with CAS.
  • Provenance: who (agent, model, run) did what, why, for which ticket, in the commit itself.
  • Knowledge delivery: the right notes arrive with the path, stale notes are visible, merges produce drafts.
  • Operations: one binary, one directory to back up, an audit log.

Where git is still better today

  • Ecosystem: every editor, CI system and hosting product speaks git. agit has a bridge, an MCP server, two SDKs and a web UI.
  • History surgery: rebase, interactive rebase, bisect, filter-repo, amend.
  • Huge binaries today: delta compression, LFS, partial clone, sparse checkout. agit's answer is designed and partly built.
  • Hosting features beyond code: issues, projects, discussions, packages, runners.
  • Multi-region availability and frozen formats.

Keep a git mirror through agit git export for the humans and tools that need git while the agents work in agit.

The agent loop

Read, claim, checkpoint, commit with intent, review, remember.

Every step has a CLI form, an HTTP endpoint, an MCP tool and an SDK method. This is the loop the Claude Code integration enforces with hooks.

Identify yourself

Set AGIT_AGENT (and optionally AGIT_MODEL, AGIT_RUN_ID). Every commit, lease, review and note carries it.

Read before you touch

agit know context src/auth/login.rs: notes, suggested tags, recent commits, leases, open PRs, active agents. One request instead of eight.

Claim what you will change

agit lease claim src/auth --ttl 30m. Others see it; commits by others into it fail.

Checkpoint before risk

agit checkpoint -m "before the rewrite", then agit restore if it goes wrong.

Commit with intent

agit commit -m "what" --intent "why" --task SEC-12. Policies can require it on protected branches.

Open a pull request, get reviewed, merge

agit pr create --push; a reviewer agent comments with a kind and approves; the merge happens on the server with CAS.

Record what you learned

agit know add -t "…" --tag kind:gotcha --path src/auth/**. The next agent gets it with the path.

export AGIT_AGENT=coder-1 AGIT_MODEL=my-model AGIT_RUN_ID=run-42

agit know context src/auth/login.rs --json
agit lease claim src/auth --ttl 30m --note "rotate session tokens"
agit checkpoint -m "before rewriting session handling"

# ... edit ...
agit add -A
agit commit -m "Rotate session tokens on login" \
  --intent "Close the fixation window reported in SEC-12" --task SEC-12

agit pr create --push -t "Rotate session tokens" --intent "..." --task SEC-12
agit pr view 1 --json            # commits, changes, mergeable, conflicts, reviews

agit know add -t "Session store is eventually consistent" \
  --tag kind:gotcha --tag area:auth --path 'src/auth/**' --commit HEAD \
  -b "Reads after a token rotation can lag by up to 200 ms; retry once."
agit lease release --all

Error handling is a table, not a guess: ref_conflict → fetch and retry; lease_conflict → pick other work or wait; policy_violation → read the message (missing intent, approvals, or a direct push to a protected branch); merge_conflicts → resolve the markers, add, commit.

Very large projects

Designed for repositories the size of a game engine.

An 80 GB repository with large binaries, thousands of entities and tens of thousands of commits is the target workload for the storage and transfer design. Here is what that design is, what is built, and what is still ahead.

Content addressing and dedup built

Every blob, tree and commit is stored once by its BLAKE3 id. A 2 GB asset referenced from 500 commits costs 2 GB once. Unchanged subtrees share their tree objects across every commit.

Only the delta travels built

Push and fetch negotiate with want/have: the client asks which ids the server is missing and sends only those. A one-texture change in an 80 GB tree transfers one blob, the changed trees and one commit.

Status without reading blobs built

Tree entries carry sizes, the index keeps a stat cache and cached directory ids. status and ls-tree never open file contents; a commit re-encodes only the directories that changed.

Append-only pack segments built

Objects go into zstd-compressed segments that roll every 256 MiB, with a checksummed index published atomically. No file-per-object explosion, no repack needed to stay fast.

Blob tiers and chunked large objects planned

Hot objects on local NVMe, everything in an S3-compatible tier as the durability anchor; multi-gigabyte files split into content-defined chunks so a small edit to a big binary stores a small delta. Phase 2 of the roadmap.

Partial and resumable clone planned

Clone the trees and the files you need, fetch blobs on demand, resume a dropped transfer without re-sending finished segments. Acceptance test in the roadmap: a 1 GiB clone resumes after a drop.

How agit handles large repositories, with the honest limits of 0.1.0 →

The platform

One binary hosts repositories, pull requests, policies, leases, events and knowledge.

agit-server is an HTTP server over plain files. No database, no workers. The web UI, both SDKs and the MCP server all follow the same documented API.

Repository home in the agit web UI
Repository home: tree, branches, recent activity.
Pull request view with typed comments and reviews
Pull request with typed comments, reviews, checks and mergeability.
Commit list filtered by agent, intent and task
Commits with agent, intent and task filters.
Knowledge base browser
Knowledge browser: notes, tags, staleness, drafts from merges.
agit + Claude Code

What Claude can do with agit that it cannot do with git.

With plain git, Claude edits files and runs git commit; nothing stops it from overwriting another agent's work, forgetting why a change was made, or discovering a conflict after an hour. With agit, the repository itself enforces the discipline.

Typed tools instead of shell parsing built

agit mcp exposes 33 tools over the Model Context Protocol: agit_status, agit_context, agit_lease_claim, agit_checkpoint, agit_commit, agit_pr_create, agit_pr_review, agit_know_add and more. Results carry the same JSON and error codes as the CLI, so Claude branches on lease_conflict rather than guessing from text.

Hooks that enforce, not suggest built

Five Claude Code hooks run deterministically: an edit under another agent's exclusive lease is blocked before the write; the path's notes and open PRs are injected before every edit; a lease is claimed automatically after an edit; a checkpoint is taken on every stop; agit commit without --intent is refused with the corrected command.

Context that arrives with the file

Before Claude touches src/cart/total.rs it sees "Totals are computed in minor units [kind:fact]", "Rounding differs per currency [kind:gotcha]", the open PR touching the file and who else holds a lease nearby. No prompt engineering, no wiki lookup.

Many Claudes, one repository

Each Claude Code session gets its own workspace and agent id. Leases keep them out of each other's files, compare-and-swap refs keep their pushes from racing, policies keep them off main without a review, and the event stream lets an orchestrator watch all of them.

Set up the Claude Code integration →

Status and roadmap

0.1.0 is a working system, not a finished one.

Six phases, each with acceptance criteria and benchmark targets. The local core is complete; large parts of the server and platform shipped early as a single node.

0 · Local core built

Object model, index, refs with CAS, leases, events, workspaces, checkpoints, merge, JSON everywhere.

1 · Performance in progress

Pack segments and a ref journal with group commit are in; the 10k commits/s single-process target, million-file status and token-efficient views are open.

2 · Protocol and server in progress

Clone/push/pull, CAS refs, scoped tokens, SSE are in; Raft replication, blob tiers, resumable transfer, idempotency keys are open.

3 · Platform in progress

Pull requests, reviews, policies, webhooks, web UI and git bridge are in; compaction of micro-commits and symbol navigation are open.

4 · Knowledge and AI in progress

Notes, tag rules, BM25 search, staleness, drafts, context packs, MCP server and SDKs are in; in-repository note objects and embeddings are open.

5 · Self-hosting and 1.0 planned

agit developed on agit, format freeze, normative spec, conformance suite, security review.

Try it on one repository this afternoon.

One binary for the client, one for the server, a git bridge to import what you have and export what the humans need.

curl -fsSL https://raw.githubusercontent.com/shadow-kernel/agit/main/scripts/install.sh | sh
agit --version