1. Installation
agit ships as two static binaries: agit (the CLI, which also contains the MCP server and the git bridge) and agit-server. Pick one method. All of them end with agit --version printing agit 0.1.0.
Downloads agit-<version>-<target>.tar.gz from the GitHub release, verifies it against the published .sha256 and installs both binaries into ~/.local/bin (or /usr/local/bin as root). macOS arm64 and x86_64, Linux x86_64 and aarch64.
curl -fsSL https://raw.githubusercontent.com/shadow-kernel/agit/main/scripts/install.sh | sh agit --version
Options: --version v0.1.0, --prefix /usr/local (with sudo sh -s --), --bin-dir DIR, --dry-run, --no-verify. Each has an environment variable (AGIT_VERSION, AGIT_PREFIX, AGIT_BIN_DIR) for curl | sh use. Make sure ~/.local/bin is on your PATH.
Requires a Rust toolchain 1.89 or newer and git on PATH if you want agit git import|export. The first build compiles about 300 crates and takes a few minutes.
git clone https://github.com/shadow-kernel/agit cd agit cargo build --release # both binaries in target/release export PATH="$PWD/target/release:$PATH" agit --version # only the CLI, into ~/.cargo/bin cargo install --path crates/agit-cli # only the server cargo build --release -p agit-server # what CI runs: fmt, clippy -D warnings, all tests make check
Images at ghcr.io/shadow-kernel/agit for linux/amd64 and linux/arm64, tagged <version>, <major.minor> and latest. The image contains agit-server, the agit CLI, git and the built web UI, runs as uid 10001 and has a health check.
docker run -d --name agit \ -p 127.0.0.1:7878:7878 \ -v agit-data:/data \ -e AGIT_SERVER_TOKEN="$(openssl rand -hex 32)" \ ghcr.io/shadow-kernel/agit:0.1.0 docker logs -f agit curl -s http://127.0.0.1:7878/api/v1/health # the CLI from the image docker exec agit agit --version docker run --rm -v "$PWD":/work -w /work --entrypoint agit ghcr.io/shadow-kernel/agit:0.1.0 status --json # build locally from a checkout docker build -t agit:dev .
homebrew/agit.rb is a formula template that the release workflow renders and attaches to each release as agit.rb. Publishing it to a tap is a manual step; until then install straight from the release asset.
brew install --formula https://github.com/shadow-kernel/agit/releases/download/v0.1.0/agit.rb
brew services start agit # local server on 127.0.0.1:7878, data in $(brew --prefix)/var/agit
Download agit-<version>-x86_64-pc-windows-msvc.zip from the releases page, unpack it and put the directory on PATH. The CLI and the server work on Windows; the Claude Code hooks are bash scripts and need WSL or Git Bash with python3 or jq.
First checks and identity
agit --version # agit 0.1.0 agit-server --help # --data-dir, --listen, --token, --web-dir # author identity: per repository ... agit config user.name "Dana Developer" agit config user.email dana@example.com # ... or globally through the environment export AGIT_AUTHOR_NAME="Dana Developer" AGIT_AUTHOR_EMAIL=dana@example.com
Agents additionally set AGIT_AGENT (and optionally AGIT_MODEL, AGIT_RUN_ID, AGIT_ON_BEHALF_OF); see section 5.
Optional components
| Component | Where | Needs |
|---|---|---|
| Web UI | web/ | Node 22 and pnpm (cd web && pnpm install && pnpm build), or the agit-web-<version>.tar.gz release asset; served with agit-server --web-dir web/dist |
| Python SDK | sdk/python | Python 3.10+, pip install -e sdk/python, no runtime dependencies |
| TypeScript SDK | sdk/typescript | Node 18+, Deno or Bun; @agit/sdk |
| MCP server | built into agit | any MCP client; agit mcp runs over stdio |
| Claude Code hooks | integrations/claude-code/ | bash 3.2+, python3 or jq; install.sh |
2. The client, used like git
Every command below also accepts --json (or AGIT_JSON=1) and -C <dir>. The human output is shown where it is shorter.
Create a repository and commit
mkdir demo && cd demo
agit init
printf '# demo\n' > README.md
mkdir src && printf 'fn main() {\n println!("hello");\n}\n' > src/main.rs
agit status
agit add README.md src
agit commit -m "Initial commit" --intent "Bootstrap the demo project" --task DEMO-1
agit log
agit status --json
{"ok":true,"result":{"workspace":"main","branch":"main","staged":[],"unstaged":[],"untracked":[],"conflicts":[],"merge_in_progress":false}}
--intent says why, --task links a ticket. Both are optional locally; server policies can require them, so it is a good habit from the first commit. A failed command is one JSON object and a non-zero exit code:
$ agit commit --json -m "x"; echo "exit=$?"
{"ok":false,"error":{"code":"nothing_to_commit","message":"nothing to commit","retryable":false,"details":null}}
exit=1
Branches, merges and conflicts
agit branch feature/greeting agit switch feature/greeting # alias: checkout; -c creates # edit src/main.rs ... agit commit -a -m "Greet the world" --intent "Make the greeting friendlier" --task DEMO-2 agit switch main # edit the same line differently ... agit commit -a -m "Greet agit" --intent "Mention the tool" --task DEMO-3 agit merge feature/greeting --json; echo "exit=$?"
{"ok":true,"result":{"kind":"conflicts","tree":"84c98e13…","conflicts":[{"path":"src/main.rs","kind":"content","base":"da3d0fe7…","ours":"b5f319df…","theirs":"eb9b58f5…"}],"auto_merged":[]}}
{"ok":false,"error":{"code":"merge_conflicts","message":"merge produced conflicts in 1 file(s)","retryable":false,"details":{"count":1}}}
exit=3
# resolve the markers (they include the base version), then agit add src/main.rs agit commit -m "Merge feature/greeting" --intent "Combine both greetings" agit log --graph --oneline agit merge --abort # at any point before that commit agit diff --stat HEAD~2 HEAD agit diff --staged
A fast-forward is reported as {"kind":"fast_forward"}, a real merge as merged, nothing to do as already_up_to_date; --no-ff forces a merge commit. switch refuses to overwrite local changes (dirty_worktree, exit 3) unless you pass --force. Renames are detected in diff and show.
Stash, checkpoints, restore
agit stash # includes untracked files agit stash list agit stash pop agit checkpoint -m "before rewriting helper" --json # {"ok":true,"result":{"id":"4cc2e92e…","tree":"b37c8a4e…","previous":null,"changes_vs_head":2,"created":true}} agit checkpoint --if-changed # created:false when nothing changed agit checkpoint list agit checkpoint restore 4cc2e92e… # whole working tree, untracked files included agit restore HEAD # discard all local changes
Checkpoints live on refs/checkpoints/<workspace>, never show up in agit log, and agit gc expires them after 30 days by default.
Blame, grep, reflog, reset, revert, cherry-pick, gc
agit blame src/main.rs # agent id shown instead of author when a commit has one agit grep 'println' --json # working tree; --rev HEAD~2 for a revision agit reflog -n 3 # every HEAD and branch move agit reset --hard HEAD~1 # itself logged, so undoable with another reset agit revert HEAD agit cherry-pick HEAD~1 agit tag v0.1.0 agit gc --dry-run --json # unreachable objects older than the grace period, expired reflog and checkpoints agit fsck
Ignore rules come from .agitignore and .gitignore, both honored. agit root --json tells you the working directory, common directory, workspace and branch from anywhere inside a repository.
Import from git, export to git
agit git import ../gitproj --into imported --json # {"ok":true,"result":{"commits":2,"trees":2,"blobs":1,"branches":["main"],"tags":[],"skipped_commits":0}} agit -C imported log --json | jq '.result[0] | {message, intent, task, meta}' # Intent:/Task:/Agent:/Model: trailers become fields; the git SHA is kept in meta["git.sha"] agit -C imported git export gitproj-export --json # via git fast-import; incremental on re-run
The bridge shells out to the git binary. Full history, branches, tags, modes, symlinks and submodule pins round-trip; re-running an import is incremental. Keep a git mirror this way for the tools and people who need git while the agents work in agit.
3. The server
agit-server is one static binary: an HTTP server that keeps every repository as plain files under one data directory. No database, no cache, no background worker. The HTTP contract is docs/API.md; the web UI, both SDKs and the CLI follow it.
Run it
agit-server --data-dir ./agit-data --listen 127.0.0.1:7878 # equivalent AGIT_DATA_DIR=./agit-data AGIT_LISTEN=127.0.0.1:7878 agit-server curl -s http://127.0.0.1:7878/api/v1/health # {"status":"ok","version":"0.1.0"}
| Variable | Flag | Default | Purpose |
|---|---|---|---|
AGIT_DATA_DIR | --data-dir | ./agit-data | directory holding every repository; the only state |
AGIT_LISTEN | --listen | 127.0.0.1:7878 | socket address (0.0.0.0:7878 in containers) |
AGIT_SERVER_TOKEN | --token | unset (open mode) | root bearer token; an empty value is a (bad) token, not "off" |
AGIT_WEB_DIR | --web-dir | unset | built web UI, served at / with SPA fallback |
RUST_LOG | info,tower_http=info | log filter; tower_http=debug logs each request | |
AGIT_FSYNC | refs | durability: refs, all, none |
Authentication and access
Without AGIT_SERVER_TOKEN the server is open: every request acts as an anonymous root. That is fine on 127.0.0.1 for development and nowhere else.
Root token. Grants every permission and bootstraps everything else. Generate it with openssl rand -hex 32, keep it in an env file or secret, rotate by restarting with a new value. Clients send it as Authorization: Bearer: AGIT_TOKEN for the CLI, the token option in the SDKs, the settings popover in the web UI.
Scoped tokens. Per agent, per job, per repository, optionally bound to an agent identity and with an expiry. A token can only grant scopes its creator holds; * scopes need root.
U=http://127.0.0.1:7878/api/v1; H="Authorization: Bearer $ROOT"
curl -s -X POST -H "$H" -H 'content-type: application/json' $U/auth/tokens \
-d '{"name":"coder-1 laptop","agent":"coder-1","scopes":[{"repo":"demo","access":"write"}],"ttl_secs":86400}'
# {"token":"agit_da83a014…","id":"tok_803401c4e6","name":"coder-1 laptop","agent":"coder-1","scopes":[{"repo":"demo","access":"write"}],…}
curl -s -H "Authorization: Bearer agit_da83a014…" $U/auth/whoami
# {"principal":"tok_803401c4e6","agent":"coder-1","root":false,"scopes":[{"repo":"demo","access":"write"}]}
curl -s -H "$H" $U/auth/tokens # metadata only, hashes on disk
curl -s -X DELETE -H "$H" $U/auth/tokens/tok_803401c4e6
scopes:{repo: "<name>" | "*", access: "read" | "write" | "admin"}.GETneeds read; other methods write; repository create/delete,policy,keys,webhooks,knowledge/rulesand/auth/*need admin. A principal only sees the repositories its scopes cover.agent: binds the token to an identity. Requests made with it act as that agent regardless ofX-Agit-Agent, so events, leases, PR authorship and policy checks cannot be spoofed by header.- Every mutation and every denied request is appended to
<data-dir>/audit.jsonlwith time, principal, agent, method, path and status.
The next release adds SSH-key authentication: operators register ssh-ed25519 public keys with per-repository scopes (and start the server with --admin-key ~/.ssh/id_ed25519.pub instead of a shared secret), clients prove possession by signing a server challenge, agit push signs in automatically with ~/.ssh/id_ed25519 or ssh-agent, sessions are short-lived tokens, and a server without any credential configured refuses to listen on a non-loopback address. Until it ships, use scoped tokens bound to agents.
Docker and Compose
docker run -d --name agit -p 127.0.0.1:7878:7878 -v agit-data:/data \ -e AGIT_SERVER_TOKEN="$(openssl rand -hex 32)" ghcr.io/shadow-kernel/agit:0.1.0 # docker-compose.yml in the repository root: named volume, token passed through from the host AGIT_SERVER_TOKEN=$(openssl rand -hex 32) docker compose up -d docker compose up -d --build # build from the checkout instead of pulling
Bind mounts must be writable by uid 10001. The compose file binds 127.0.0.1:7878 (use "7878:7878" to expose directly), passes AGIT_SERVER_TOKEN through only when set on the host, and defines a health check.
systemd
sudo useradd --system --home-dir /var/lib/agit --shell /usr/sbin/nologin agit
sudo install -m 0755 agit-server agit /usr/local/bin/
sudo mkdir -p /etc/agit && sudo install -m 0640 -o root -g agit deploy/agit-server.env /etc/agit/
sudo install -m 0644 deploy/agit-server.service /etc/systemd/system/
sudo $EDITOR /etc/agit/agit-server.env # set AGIT_SERVER_TOKEN, AGIT_WEB_DIR
sudo systemctl daemon-reload && sudo systemctl enable --now agit-server
journalctl -u agit-server -f
The unit is hardened (ProtectSystem=strict, NoNewPrivileges, empty capability set, syscall filter, StateDirectory=agit, LimitNOFILE=65536), listens on 127.0.0.1:7878 and expects a reverse proxy in front.
Reverse proxy and TLS
The server speaks plain HTTP; terminate TLS in Caddy or nginx. Three settings matter: no response buffering and long read timeouts for /api/v1/repos/*/events/stream (long-lived SSE), no request body limit (pushes upload object streams in one request), and Authorization forwarded unchanged.
agit.example.com {
encode zstd gzip
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
Referrer-Policy "strict-origin-when-cross-origin"
-Server
}
reverse_proxy 127.0.0.1:7878 {
flush_interval -1 # server-sent events: do not buffer
transport http {
read_timeout 0
write_timeout 0
dial_timeout 10s
}
}
log {
output file /var/log/caddy/agit.log
}
}
client_max_body_size 0; # pushes can be large location ~ ^/api/v1/repos/[^/]+/events/stream$ { proxy_pass http://127.0.0.1:7878; proxy_http_version 1.1; proxy_set_header Connection ""; proxy_buffering off; proxy_cache off; proxy_read_timeout 24h; proxy_send_timeout 24h; } location / { proxy_pass http://127.0.0.1:7878; proxy_http_version 1.1; proxy_set_header Connection ""; proxy_set_header Host $host; proxy_request_buffering off; # stream pushes instead of spooling to disk proxy_read_timeout 300s; }
Full file with TLS, HSTS and certbot instructions: deploy/nginx.conf.
Data layout, backups, monitoring, upgrades
audit.jsonl denied requests and every mutation
auth/ scoped tokens (hashes) and metadata
repos/<repo>/
meta.json {name, default_branch, created_ms}
objects/pack/ append-only segments seg-*.agp with .idx (AGX1)
refs/, refs.journal branches, tags, journal with group commit
events.jsonl per-repository event log
leases/ pulls/ knowledge/notes/ policy.json keys.json webhooks.json
- Backups. The data directory is the only state. Snapshot it (filesystem snapshot, or
tarof a stopped or quiet server), ship copies off-host and encrypt them:webhooks.jsonholds secrets,auth/holds token hashes, notes may contain anything agents wrote. - Liveness.
GET /api/v1/healthanswers without a token. Activity.GET /repos/{repo}/events?since=or the SSE stream;GET /repos/{repo}/agents. Audit. tailaudit.jsonlfor403bursts and admin mutations. - Capacity. Disk under
repos/*/objectsis the number to graph. Pushes and merges are fsync-bound, so IOPS and latency matter more than throughput. Starting points (not measurements): 1 vCPU / 512 MB for personal use, 2 vCPU / 1-2 GB for a team with tens of agents, 4+ vCPU / 4 GB / NVMe for hundreds of concurrent agents. - Upgrades. Replace the binaries and restart. Before 1.0 a minor version may change on-disk formats; the CHANGELOG says so under "Changed" when it happens.
Policies (branch protection)
Per repository, GET/PUT /repos/{repo}/policy (admin), also editable in the web UI. Enforced on pushes (refs/update) and on pulls/{n}/merge; violations are 403 policy_violation with a message that names the rule.
curl -s -X PUT -H "$H" -H 'content-type: application/json' $U/repos/demo/policy -d '{
"protected_branches": ["main", "release/*"],
"require_pull_request": true,
"require_approvals": 1,
"require_intent": true,
"require_agent": true,
"require_checks": false,
"block_on_blockers": true,
"allowed_merge_agents": [],
"allowed_push_agents": [],
"max_files_per_commit": 0,
"require_signed": false
}'
Rules: protected branches cannot be deleted; with require_pull_request they only move through PR merges; approvals count the latest decision per reviewer and exclude the author; any request_changes blocks; unresolved blocker comments block; require_intent, require_agent, max_files_per_commit and require_signed are checked on every new commit the update introduces.
Signing keys
agit key generate # ~/.agit/keys/<AGIT_AGENT>.key, mode 0600 agit key generate --register # and trust it for this agent on the remote (admin scope) agit commit -m "..." --intent "..." # signed automatically once a key named after the agent exists agit verify HEAD # offline: the public key travels inside the commit curl -s -H "$H" $U/repos/demo/keys # registry: which keys are trusted for which agent
A valid signature proves the commit was made by whoever holds the agent's private key; the registry decides whether that key is trusted for the agent. The policy require_signed refuses unsigned or untrusted commits on protected branches.
Webhooks
curl -s -X POST -H "$H" -H 'content-type: application/json' $U/repos/demo/webhooks \
-d '{"url":"https://ci.example.com/agit","kinds":["commit","pull.*"],"secret":"'"$(openssl rand -hex 16)"'"}'
curl -s -X POST -H "$H" $U/repos/demo/webhooks/<id>/test # queues a ping
Deliveries carry X-Agit-Event, X-Agit-Repo, X-Agit-Delivery (idempotency key) and, with a secret, X-Agit-Signature: blake3=<hex> (keyed BLAKE3 over the body). Three attempts with backoff. Restrict the server's egress: it POSTs to whatever URL an admin registers.
Web UI
cd web && pnpm install && pnpm build && cd .. agit-server --data-dir ./agit-data --web-dir web/dist # UI at http://127.0.0.1:7878/ cd web && pnpm dev # hot reload at http://localhost:5173
Code browsing with syntax highlighting, commits with agent/intent/task filters, diffs and compare, pull requests with inline comments and reviews, agents, the lease board, the knowledge browser, settings for policy, webhooks, rules and keys, and a token admin page. The UI keeps the token in localStorage and sends it as a header; there are no cookies.
4. Client meets server
Remotes, push, clone, pull
export AGIT_TOKEN=agit_da83a014… # the client's credential agit remote add origin http://127.0.0.1:7878/api/v1/repos/demo agit push --create # creates the remote repository, CAS on the ref # {"ok":true,"result":{"remote":"origin","branch":"main","old":null,"new":"44b9a0f2…","objects_sent":33,"up_to_date":false}} cd .. && agit clone http://127.0.0.1:7878/api/v1/repos/demo demo-b && cd demo-b agit fetch # refs/remotes/origin/* agit pull # fetch + merge (fast-forward when possible) agit push origin feature/x
Pushes send only the objects the server is missing and update the ref with compare-and-swap; a concurrent move answers ref_conflict (exit 75): pull, then push again. A non-fast-forward push is detected on the client before any network write.
Pull requests and reviews
agit switch -c feature/config # ... edit, add, commit with --intent and --task ... agit pr create --push -t "Load greeting from Config" -b "First step." \ --intent "Make the greeting configurable for DEMO-7" --task DEMO-7 --json agit pr view 1 --json | jq '.result | {mergeable, conflicts, commits: (.commits|length)}' # as reviewer-1, in another clone AGIT_AGENT=reviewer-1 agit pr comment 1 --kind blocker --path src/config.rs --line 4 \ -b "Hard-coded greeting; read it from the environment." AGIT_AGENT=reviewer-1 agit pr review 1 --decision request_changes -b "See blocker" # ... author fixes, pushes; reviewer resolves the comment and approves ... AGIT_AGENT=reviewer-1 agit pr review 1 --decision approve -b "lgtm" AGIT_AGENT=reviewer-1 agit pr merge 1 # three-way merge on the server, CAS on main agit pr list --state merged
Comment kinds: question, suggestion, blocker, note. Decisions: approve, request_changes, comment. A merge refused by policy answers policy_violation with the rule in the message; a merge with conflicts answers merge_conflicts and pr view lists them.
Knowledge: notes, rules, context
# tag rules: which tags a note about a path should carry (admin) curl -s -X PUT -H "$H" -H 'content-type: application/json' $U/repos/demo/knowledge/rules \ -d '[{"pattern":"src/**","tags":["area:core","lang:rust"]}]' agit know add -t "Config is read once at startup" --tag kind:fact --tag area:core \ --path 'src/config.rs' --commit HEAD -b "Changing GREETING needs a restart." agit know context src/config.rs # notes, suggested tags, recent commits, leases, open PRs, active agents agit know search --query "startup config" --tag area:core agit know sync # push local-only notes, refresh the offline cache in .agit/knowledge
Notes carry a valid_at commit; when a covered path changes afterwards the note is stale until someone validates it. Every merged pull request produces a draft note (title, intent, task, changed files, reviews) that an agent accepts or discards. Search is BM25 over title, body, tags and paths.
Events, server-side leases, activity
agit events --follow --kind lease. # local log curl -N -H "$H" "$U/repos/demo/events/stream?since=0" # SSE, replay then live curl -s -H "$H" "$U/repos/demo/events?since=120&limit=50" curl -s -X POST -H "$H" -H 'content-type: application/json' $U/repos/demo/leases \ -d '{"holder":"coder-1","paths":["src/auth/**"],"mode":"exclusive","ttl_secs":1800,"note":"rotate tokens"}' curl -s -H "$H" $U/repos/demo/agents # per-agent commits, leases, open PRs, last seen
Local leases (in .agit/leases/) are for agents sharing a filesystem; server leases are for agents on different machines. The context endpoint and the web UI's lease board show the server ones.
5. Agents
Identity
export AGIT_AGENT=coder-1 AGIT_MODEL=my-model-v3 AGIT_RUN_ID=run-2026-10-19-a
export AGIT_TOKEN=… # a scoped token bound to coder-1, write on the repositories it works in
AGIT_AGENT becomes the commit's agent.id, the lease holder, the X-Agit-Agent header and the default signing-key name. Use a stable id per role (coder-1, reviewer-1) and put per-run correlation in AGIT_RUN_ID.
The loop
Read before you touch
agit know context <path> --json
Claim what you will change
agit lease claim <paths> --ttl 30m --note "…"; renew while working, release --all when done
Work in your own workspace or branch
agit ws new coder-1 or agit switch -c feature/x
Checkpoint before risky edits
agit checkpoint -m "…", agit restore <id> to roll back
Commit with intent
agit commit -m "what" --intent "why" --task T-1 --meta ci.tests=pending
Push and open a pull request
agit pr create --push -t "…" --intent "…" --task T-1
Record what you learned
agit know add -t "…" --tag kind:gotcha --path 'src/x/**' -b "…"
Error handling
| code | exit | meaning | what to do |
|---|---|---|---|
ref_conflict | 75 | someone moved the ref you based your update on | fetch or pull, re-check, retry |
lock_timeout | 75 | an internal lock was busy (10 s refs, 5 s leases/events) | back off, retry |
lease_conflict | 3 | another agent holds the path | pick other work, wait for expiry, or negotiate; never blind-retry |
merge_conflicts | 3 | three-way merge needs a decision | resolve files with diff3 markers, agit add, commit |
dirty_worktree | 3 | local edits would be overwritten | checkpoint or commit first |
policy_violation | 1 | server policy refused the change | read the message: missing intent, approvals, blockers, or a direct push to a protected branch |
forbidden | 1 | missing or insufficient token scope | ask the operator for a token with the needed scope |
hash_mismatch, corrupt_object | 1 | storage returned bytes that do not match the id | agit fsck; restore the object from a clone or backup |
MCP server
agit mcp runs a Model Context Protocol server over stdio with 33 tools that return the same JSON as the CLI; failures come back as isError with the same codes. Register it in any MCP client, started inside a repository:
{ "mcpServers": { "agit": { "command": "agit", "args": ["mcp"], "env": { "AGIT_AGENT": "coder-1", "AGIT_MODEL": "my-model" } } } }
| Group | Tools |
|---|---|
| Repository state | agit_status, agit_log, agit_show, agit_diff, agit_read_file, agit_ls, agit_branches, agit_workspaces, agit_events |
| Writing | agit_add, agit_commit (intent, task, agent, meta, sign), agit_checkpoint, agit_checkpoint_list, agit_restore, agit_switch, agit_merge |
| Coordination | agit_lease_claim, agit_lease_release, agit_lease_list, agit_lease_check |
| Remote and pull requests | agit_push, agit_pull, agit_pr_create, agit_pr_list, agit_pr_view, agit_pr_review, agit_pr_comment, agit_pr_merge |
| Knowledge | agit_context, agit_know_search, agit_know_get, agit_know_add, agit_know_sync |
The server's instructions describe the loop above, so a model that reads them knows to call agit_context before editing and agit_lease_claim for the paths it will change.
Claude Code integration
Two halves that work independently and are better together: the MCP server gives Claude typed tools; five hooks make the discipline deterministic, because a model that forgot to call agit_context still gets the notes, and a model that tries to edit a path another agent owns is stopped before the write happens.
cd /path/to/your/agit/repo /path/to/agit/integrations/claude-code/install.sh # project scope: hooks + settings + CLAUDE.md snippet /path/to/agit/integrations/claude-code/install.sh --mcp # also writes .mcp.json # or register the MCP server by hand claude mcp add --scope project agit -e AGIT_AGENT=claude-code -- agit mcp # options: --agent <id>, --global (every agit repo on the machine), --uninstall integrations/claude-code/test.sh # self-test: builds a temp repo, simulates every hook
| Hook | Event | Behaviour |
|---|---|---|
pre-edit.sh | PreToolUse on Edit / Write / MultiEdit / NotebookEdit | Runs agit lease check. A path under another agent's exclusive lease exits 2: the edit is not performed and Claude sees who holds the lease and when it expires. Otherwise injects the path's context (note titles with kind, suggested tags, open PRs, other agents' shared leases) as additionalContext, cached 60 s. |
post-edit.sh | PostToolUse, same tools | Claims a 30-minute exclusive lease on the file if none of this agent's leases covers it (AGIT_HOOK_LEASE_TTL changes the TTL). Covering directory or glob leases are reused, never duplicated. |
checkpoint.sh | Stop, SubagentStop | Records agit checkpoint -m "claude-code stop" when the tree changed. Never fails, never prints. |
session-start.sh | SessionStart | Briefing: repository, branch, HEAD, dirty counts, remote, agent id, active leases with minutes left, active hooks, the loop and the error-code rules. |
pre-commit-guard.sh | PreToolUse on Bash | agit commit without --intent is blocked (exit 2) with the corrected command; git commit / git push inside an agit repository get a reminder; agit pr create without --intent gets a reminder. |
Hooks are shell scripts executed with your user's permissions. Read integrations/claude-code/hooks/*.sh before installing them, as you would any pre-commit hook. They only run agit subcommands and python3 -I or jq, and send nothing but the path to your configured agit server. AGIT_HOOKS_DISABLE=1 pauses all of them.
SDKs
agit-sdk (sdk/python): zero dependencies, Python 3.10+, typed client for every endpoint, SSE streaming, typed errors with the same codes, and an AgentSession helper that claims leases, opens pull requests, records notes and releases leases on exit.
from agit import Client, AgentSession
client = Client("http://127.0.0.1:7878/api/v1", agent="coder-1") # token from AGIT_TOKEN
with AgentSession(client, "demo", "coder-1") as s:
ctx = s.context("src/auth/login.rs") # notes, suggested tags, recent commits, leases, open PRs
s.claim(["src/auth"], ttl_secs=1800, note="session refactor")
... # edit, commit and push with the CLI or MCP tools
s.open_pr(title="Rotate session tokens", source="feature/x", intent="close SEC-12")
s.remember(title="Session store lags", body="...", tags=["kind:gotcha", "area:auth"], paths=["src/auth/**"])
@agit/sdk (sdk/typescript): zero dependencies, ESM + CJS, Node 18+, Deno, Bun and browsers; SSE over fetch with reconnect, typed errors, AgentSession with withLeases(paths, fn).
import { AgitClient, AgentSession } from "@agit/sdk";
const client = new AgitClient({ baseUrl: "http://127.0.0.1:7878/api/v1", agent: "coder-1" });
const session = new AgentSession(client, "demo", "coder-1");
const ctx = await client.getContext("demo", "src/auth/login.rs");
await session.withLeases(["src/auth"], async () => {
// edit, commit and push with the CLI or MCP tools
await client.pulls.create("demo", { title: "Rotate session tokens", source: "feature/x", intent: "close SEC-12" });
});
for await (const ev of client.streamEvents("demo", { since: 0 })) console.log(ev.kind, ev.data);
Many agents in one repository
- One workspace per agent.
agit ws new coder-2 --agent coder-2creates../repo.coder-2on branchws/coder-2. Never share a working directory. - Lease etiquette. Claim the smallest covering path, set a TTL that matches the task, renew while working, release on completion. Use
--sharedfor "I am reading this". - Checkpoint cadence. One before every destructive step, one at the end of every turn (the Claude Code hooks do exactly this).
- Reviewer agents. A second identity comments with a kind, reviews, and merges under a policy that requires an approval; the author is excluded from approvals.
- Observe the fleet.
GET /repos/{repo}/agents, the SSE stream, the lease board and the Agents tab in the web UI.
6. Large repositories
The full treatment, including the design for 80 GB game repositories and the limits of 0.1.0, is on its own page. The short version for today:
- Keep single files below 4 GiB (32-bit object length fields) and size the agent's machine for the largest asset plus the largest fetch, because objects are handled in memory.
- Split engine, tools and content into repositories pinned through
.agitmodules; give agents clones of what they work on. - Lease asset directories before editing binaries; they do not merge.
- Ignore build output in
.agitignore;statuscost grows with tracked file count. - Put the server's data directory on NVMe, remove body-size limits on the proxy, back the directory up nightly.
7. Troubleshooting
| Symptom | Cause and fix |
|---|---|
not_a_repository | No .agit here or above; agit root says where you are. Secondary workspaces have a .agit file pointing at the primary. |
403 forbidden on every call | Token set on the server but missing or different on the client (AGIT_TOKEN, SDK option, web popover). Check the server was not started with an empty AGIT_SERVER_TOKEN=. |
403 … token lacks Admin access | A scoped token hitting an admin endpoint (policy, keys, webhooks, rules, repository create/delete, tokens). Use an admin or root token. |
lock_timeout | Another process held refs.lock (10 s) or leases.lock / events.lock (5 s). Retry; if it persists something is stuck holding a descriptor, not a stale file. |
| Lease conflict with yourself | The holder is the exact string in --holder / AGIT_AGENT. A lease under a different id counts as foreign; release it by id or wait for the TTL. |
hash_mismatch / corrupt_object | Storage returned bytes that do not match the id. agit fsck; agit fetch brings the object back if the server has it. |
| Hooks do nothing at session start | Check /hooks in Claude Code; run session-start.sh by hand. GUI launches may have a short PATH: set AGIT_BIN=/full/path/agit in settings.json env. |
| Context never appears in hooks | Needs a remote and a reachable server; failures are cached 60 s per path under $TMPDIR/agit-claude-hooks/. |
| SSE stream closes or buffers | Proxy buffering or read timeouts; use the Caddy or nginx settings above. |
| Push rejected as too large | client_max_body_size on the proxy; set it to 0 or a cap that fits your repositories. |
| Tags missing on the server | agit push pushes a branch; use agit push --tags to send tags. |
8. Reference
Environment variables (client)
| Variable | Meaning |
|---|---|
AGIT_JSON | true enables --json for every command |
AGIT_AGENT, AGIT_MODEL, AGIT_RUN_ID, AGIT_ON_BEHALF_OF | the agent fields on commits; agent id is also lease holder and X-Agit-Agent |
AGIT_AUTHOR_NAME, AGIT_AUTHOR_EMAIL | commit author when user.name / user.email are not configured |
AGIT_TOKEN | bearer token for clone, fetch, push, pull, pr, know, key register, mcp |
AGIT_SIGN, AGIT_KEY, AGIT_KEYS_DIR | signing mode (auto default), default key name, key directory (~/.agit/keys) |
AGIT_FSYNC | refs (default), all, none |
AGIT_PACK | 0 writes loose objects instead of pack segments |
Exit codes
0 success · 1 error · 3 conflict (merge_conflicts, lease_conflict, dirty_worktree, non_fast_forward) · 75 retryable (ref_conflict, lock_timeout). Durations take an integer with a unit: s, m, h, d.
Further reading
- The handbook: 18 chapters, every flag and JSON shape, FAQ, glossary, comparison.
- docs/API.md: the HTTP contract the UI, SDKs and CLI follow.
- docs/DEPLOYMENT.md and docs/SECURITY.md: systemd, proxies, sizing, threat model, hardening checklist.
- docs/CLAUDE-CODE.md and docs/AGENT-GUIDE.md: the integration and the loop on one page.
- docs/ARCHITECTURE.md and the RFCs: byte layouts, the planned pack, journal and replication design.