Setup

The four mappings

Everything in agit follows from four equations. Once they click, every command is obvious.

repo = agent

An agent is the sum of everything it takes to finish a job: session history, memory/, skills/, AGENTS.md. That sum is what deserves version control — and it’s a real git repository at ~/.agit/agents/<owner>/<name>/. The hub keeps its bare replica.

branch = session

Each branch is one session. Except main: main is the shared-file line — memory/, skills/, AGENTS.md — and never claims a session. A fresh repo’s first turn commit therefore lands on a session branch (that’s a real check in our test suite), never on main.

commit = one turn

Settlement is per-turn: each user turn ends in one turn commit. Turns are therefore individually referenceable, selectable, revertible — and the log reads like the story of the work, not a wall of snapshots.

How a turn gets settled depends on where the transcript lives:

• Native continuation — the runtime’s own file carries on (byte-prefix check proves it). The transcript file itself is the source of truth.
• Materialized baseline — the session was materialized from a VIEW (say, cloned onto another machine). Settlement registers baseline_bytes inside the new transcript: bytes before the baseline are history already in the repo; only what you appended gets accounted. If the hash doesn’t match, settlement refuses (exit 7) rather than double-book history.

merge = two-parent commit

Two lines run in parallel — because you forked an experiment, or because you and upstream both moved. agit merge starts a merge agent that reads both sides, picks turns, and writes a merge_summary (“what this reconciliation concluded”). agit owns the gates, isolation and validation; the agent owns understanding — it can read transcripts to decide what belongs, where git would just guess which token lines go together. The result is a two-parent commit.

No model nearby? agit merge --manual drives the same plumbing (pick / drop / summary / —continue) by hand. The resulting commit is bit-identical in shape.

The VIEW

A session never sees the raw log — it sees a VIEW: the ordered materialized context. Settlement appends turns; merges add marker/summary envelopes; revert removes events. Three invariants hold, and agit doctor enforces them:

1. every referenced event is reachable,
2. merge markers pair up,
3. the underlying log is still append-only.

Reference syntax

Shape	Meaning
exp	branch head
exp#12	turn 12 of branch exp
exp#-1	latest turn
exp#12.3	event 3 inside turn 12
exp#4..#9	a turn range
owner/repo@exp	someone else’s line
exp:path	a file as of that point
@	your own current session

@ resolves through a chain: explicit argument → AGIT_SESSION → harness env → pinned workspace → cwd match.

Next: Supported runtimes.