The guide

Install, run a server, use it like git, hand it to your agents.

Everything from the first binary to a hardened server with policies, the MCP server and Claude Code hooks. Commands are copied from real sessions against agit 0.1.0; long ids are shortened.

Developer

Install, then use the client exactly like git, with JSON when you want it.

Operator

Run agit-server: tokens, policies, Docker, systemd, TLS, backups.

Agent author

The loop, the MCP server, Claude Code hooks, Python and TypeScript SDKs.

Large projects

What to expect with tens of gigabytes and big binaries today.

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.

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

ComponentWhereNeeds
Web UIweb/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 SDKsdk/pythonPython 3.10+, pip install -e sdk/python, no runtime dependencies
TypeScript SDKsdk/typescriptNode 18+, Deno or Bun; @agit/sdk
MCP serverbuilt into agitany MCP client; agit mcp runs over stdio
Claude Code hooksintegrations/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"}
VariableFlagDefaultPurpose
AGIT_DATA_DIR--data-dir./agit-datadirectory holding every repository; the only state
AGIT_LISTEN--listen127.0.0.1:7878socket address (0.0.0.0:7878 in containers)
AGIT_SERVER_TOKEN--tokenunset (open mode)root bearer token; an empty value is a (bad) token, not "off"
AGIT_WEB_DIR--web-dirunsetbuilt web UI, served at / with SPA fallback
RUST_LOGinfo,tower_http=infolog filter; tower_http=debug logs each request
AGIT_FSYNCrefsdurability: refs, all, none

Authentication and access

Never run an open server on a reachable interface.

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"}. GET needs read; other methods write; repository create/delete, policy, keys, webhooks, knowledge/rules and /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 of X-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.jsonl with time, principal, agent, method, path and status.
In progress on main: sign in with your SSH key. in progress

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
	}
}

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 tar of a stopped or quiet server), ship copies off-host and encrypt them: webhooks.json holds secrets, auth/ holds token hashes, notes may contain anything agents wrote.
  • Liveness. GET /api/v1/health answers without a token. Activity. GET /repos/{repo}/events?since= or the SSE stream; GET /repos/{repo}/agents. Audit. tail audit.jsonl for 403 bursts and admin mutations.
  • Capacity. Disk under repos/*/objects is 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

codeexitmeaningwhat to do
ref_conflict75someone moved the ref you based your update onfetch or pull, re-check, retry
lock_timeout75an internal lock was busy (10 s refs, 5 s leases/events)back off, retry
lease_conflict3another agent holds the pathpick other work, wait for expiry, or negotiate; never blind-retry
merge_conflicts3three-way merge needs a decisionresolve files with diff3 markers, agit add, commit
dirty_worktree3local edits would be overwrittencheckpoint or commit first
policy_violation1server policy refused the changeread the message: missing intent, approvals, blockers, or a direct push to a protected branch
forbidden1missing or insufficient token scopeask the operator for a token with the needed scope
hash_mismatch, corrupt_object1storage returned bytes that do not match the idagit 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" } } } }
GroupTools
Repository stateagit_status, agit_log, agit_show, agit_diff, agit_read_file, agit_ls, agit_branches, agit_workspaces, agit_events
Writingagit_add, agit_commit (intent, task, agent, meta, sign), agit_checkpoint, agit_checkpoint_list, agit_restore, agit_switch, agit_merge
Coordinationagit_lease_claim, agit_lease_release, agit_lease_list, agit_lease_check
Remote and pull requestsagit_push, agit_pull, agit_pr_create, agit_pr_list, agit_pr_view, agit_pr_review, agit_pr_comment, agit_pr_merge
Knowledgeagit_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
HookEventBehaviour
pre-edit.shPreToolUse on Edit / Write / MultiEdit / NotebookEditRuns 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.shPostToolUse, same toolsClaims 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.shStop, SubagentStopRecords agit checkpoint -m "claude-code stop" when the tree changed. Never fails, never prints.
session-start.shSessionStartBriefing: 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.shPreToolUse on Bashagit 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/**"])

Many agents in one repository

  • One workspace per agent. agit ws new coder-2 --agent coder-2 creates ../repo.coder-2 on branch ws/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 --shared for "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; status cost 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

SymptomCause and fix
not_a_repositoryNo .agit here or above; agit root says where you are. Secondary workspaces have a .agit file pointing at the primary.
403 forbidden on every callToken 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 accessA scoped token hitting an admin endpoint (policy, keys, webhooks, rules, repository create/delete, tokens). Use an admin or root token.
lock_timeoutAnother 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 yourselfThe 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_objectStorage 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 startCheck /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 hooksNeeds a remote and a reachable server; failures are cached 60 s per path under $TMPDIR/agit-claude-hooks/.
SSE stream closes or buffersProxy buffering or read timeouts; use the Caddy or nginx settings above.
Push rejected as too largeclient_max_body_size on the proxy; set it to 0 or a cap that fits your repositories.
Tags missing on the serveragit push pushes a branch; use agit push --tags to send tags.

8. Reference

Environment variables (client)

VariableMeaning
AGIT_JSONtrue enables --json for every command
AGIT_AGENT, AGIT_MODEL, AGIT_RUN_ID, AGIT_ON_BEHALF_OFthe agent fields on commits; agent id is also lease holder and X-Agit-Agent
AGIT_AUTHOR_NAME, AGIT_AUTHOR_EMAILcommit author when user.name / user.email are not configured
AGIT_TOKENbearer token for clone, fetch, push, pull, pr, know, key register, mcp
AGIT_SIGN, AGIT_KEY, AGIT_KEYS_DIRsigning mode (auto default), default key name, key directory (~/.agit/keys)
AGIT_FSYNCrefs (default), all, none
AGIT_PACK0 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