How git works, and how to run AI agents on it

The mental model: snapshots and pointers

Three facts explain most of git.

1. A commit is a snapshot of your whole project, not a diff. Each commit records a complete tree of your files, plus pointers to the commit(s) it came from, an author, and a message. The diffs you see in tooling are computed on demand between two snapshots.
2. Commits form an append-only graph. Each commit points at its parent(s); a merge commit has more than one. History is a directed acyclic graph — the DAG. Commits are immutable: you can add new ones and move labels around, but an existing commit never changes. Even "history rewriting" obeys this — see the rebase button below.
3. A branch is just a name pointing at one commit. Not a copy of the code, not a folder — a 40-character commit ID filed under a name. HEAD is one more pointer that marks where you are, usually by pointing at a branch.

Play with the graph. Watch what each command really moves — most of them move a pointer and nothing else:

Content addressing: one hash names everything

The central design idea: every object is named by the hash of its contents. A file's contents hash to a blob ID. A directory listing (filenames + the blob IDs inside it) hashes to a tree ID. A commit (the tree ID + parent commit ID + author + message) hashes to the commit ID. Each level's name contains the names below it — a structure known as a Merkle DAG.

The consequence: a commit ID authenticates the entire history behind it. Change one byte in one file anywhere in the past, and every hash above it changes — the tree, the commit, and every descendant commit. History cannot be quietly edited — only replaced with different history under different IDs. The demo below computes real SHA-1 hashes in your browser:

blob …

100644 blob …  app.ts
tree …

tree …
parent 9c4e21ab…   author you <you@example.com>
message: "feat: compute the answer"

commit …

The four places your code lives

Every day-to-day git command moves changes between four places. Confusion about git is almost always confusion about which place a change is currently in — and therefore how protected it is.

The staging area is the step people skip explaining: it lets you compose a commit — pick these hunks, not those — instead of committing whatever happens to be on disk. And the last hop is the one that matters most in a team or a fleet: until you push, your commit exists on exactly one machine. Committed ≠ shipped. Pushed to the shared branch = shipped.

Using git well

Commits are save points

Commit small and often — every coherent step, not every day. A tight history buys you: instant rollback targets, git bisect (binary-search history to find the exact commit that broke something — O(log n) debugging), and archaeology that answers "why is this code like this?" months later via git log and git blame. With AI agents this stops being taste and becomes load-bearing: the commit is the unit of review, revert, and attribution.

The safety nets, in order of reach

• git restore <file> — discard uncommitted edits to a file. (The one net that destroys rather than recovers — it throws away work that was never committed.)
• git revert <commit> — undo a commit by adding a new commit that inverts it. Safe on shared branches; history stays truthful.
• git reset — move your branch pointer to an older commit. Fine for local, unpushed work; on a shared branch it rewrites history others built on, which is why force-pushing shared branches is banned in serious teams.
• git reflog — the flight recorder: every position HEAD has occupied, including positions "lost" to resets and rebases. When someone says git ate their commit, the reflog almost always disagrees.

Two phrases you will hear

"Rebase before merging." While you worked on a branch, main moved. Rebasing replays your commits on top of the latest main (see the rebase button in section 1), so your changes apply to current code and the eventual merge is trivial — often a fast-forward. Safe rule: rebase freely on branches only you have; never rebase commits someone else has already pulled.

"Fast-forward." When the target branch has not moved since you branched, there is nothing to reconcile — git just slides the pointer forward. No merge commit, because the histories never actually diverged.

Quick check

Worktrees — and the trap almost nobody warns you about

A worktree is an additional folder on disk attached to the same repository — same object store, same branches, separate working files. They're how you work on two branches at once without stashing, and how AI agents get isolated sandboxes without the cost of full clones.

The trap: git allows each branch to be checked out in only ONE worktree at a time. The rule is sound — two folders both "owning" a branch pointer would corrupt each other's view. The corollary: a forgotten worktree parked on main silently blocks every other checkout of main, including the automated merge job that lands finished work. If that job's error handling is quiet, completed work strands on a side branch while every dashboard reports success. This exact failure hit our own pipeline: twelve finished commits sat unmerged behind one stale worktree until an audit found them.

Who worktrees are for — and who they are not for

Three mappings to keep straight, because they are easy to blur:

• A teammate gets a clone. Worktrees never leave one machine. People collaborate through separate full copies that meet at origin via push, fetch, and pull (section 3's demo).
• A concurrent writer gets a worktree. Two processes editing the same folder collide (section 6). A worktree gives each writer its own files while sharing one object store — commits from every worktree land in the same repository.
• A feature just gets a branch. Most features never need a worktree; you switch branches in place. A worktree is only for a branch that must be active at the same time as another — a hotfix on main while a half-finished feature occupies your primary checkout, or a second agent working in parallel.

Managing worktrees: creation, lifecycle, cleanup

Worktrees never create themselves and never clean themselves up. Git gives you exactly these controls and no lifecycle beyond them:

git worktree add ../fix-login main   # create: new folder, checks out a branch
git worktree list                    # inventory — run this before anything surprises you
git worktree lock ../agent-7 --reason "agent 7 owns this"   # mark as in-use
git worktree remove ../fix-login     # delete when the work has landed
git worktree prune                   # clean metadata for folders already deleted by hand

The rule that prevents every worktree problem on this page: whoever creates a worktree owns its funeral. The lifecycle is create → work → land the work (merge or push) → remove. Nothing expires them for you — a forgotten worktree sits forever, holding its branch hostage and accumulating un-narrated changes. If a tool created it (agent orchestrators, including TermRoam, create per-agent worktrees programmatically), the tool must also remove it — and sweep for the ones it failed to.

If an agent dies or resets, is its worktree stranded?

The disk state survives perfectly — files, branch, uncommitted edits; git loses nothing. What dies with the agent is the intent: a fresh agent (or you) finds a dirty worktree with no narrative about what the edits were for. The fix is not smarter agents — it is externalizing memory into artifacts. The task spec records what is done and what is next; commit messages record why; one-commit-per-step keeps the uncommitted window tiny. Under that discipline, resetting an agent is safe: any replacement reads the spec, sees step 6 checked and step 7 not, and continues. Without it, every reset risks stranding mystery work — which is why a sweep that commits dirty, ownerless worktrees to pushed rescue branches is the backstop worth automating (TermRoam's watcher does exactly this).

Are worktrees part of the git workflow?

No — the core loop (edit → add → commit → push → merge) never requires one, and you can use git for a career without the command. They are a concurrency tool for a single machine. What has changed is that agent fleets promote them from occasional convenience to load-bearing primitive — a sandbox per writer — and vanilla git provides no management for that role: no expiry, no ownership, no orphan detection. That gap is what your orchestration layer has to fill, and it is why several of the guards in section 8 are really just worktree lifecycle management.

The immediate fix is one command — git switch --detach in the offending worktree drops the branch name without touching a single file, freeing main for checkout elsewhere. The durable fix is refusing to depend on a human noticing — that's section 7.

What changes when the committers are AI agents

Git's guarantees were designed for humans who notice things. Agents are fast, tireless, parallel — and they do not notice things. Run several against one repository and you surface failure modes human teams rarely hit:

• Many writers, one working tree. Two agents in the same checkout produce competing commits, dirty-tree collisions, and rebase chaos. Asking an agent to "be careful, another agent is working here" is a prompt, not a lock. This is the failure mode we hit most — the timeline below is what it actually looks like.
• Killed processes orphan work. An agent is terminated mid-task — quota, crash, operator — and its half-finished step sits uncommitted in a worktree. Recall section 1: git protects the committed. Nothing sweeps for orphaned working trees by default; our own audit found two whole features rotting that way.
• Status is a claim, not a fact. An orchestrator marks a task "complete" when its checklist finishes. Whether the commits actually reached the shared branch is a separate, later, failable step — see the worktree trap. "Complete" and "merged" must be verified independently, forever.
• Check-time ≠ run-time. Agents probe for a tool in one shell environment and execute in another (login shell vs. daemon PATH is the classic). The probe passes; the run exits 127; a naive restart loop hammers the API until someone looks. Probe and execution environments must match — or the wrapper must recognize the failure class and halt.
• Volume changes the economics. A human drops work once a quarter and remembers doing it. Agents ship dozens of tasks a day; a 2% silent-drop rate is several lost features a week that nobody remembers to look for.

Anatomy of a collision (the one we hit most)

The reason shared-checkout collisions are so damaging is that git raises no error — every command each agent runs is individually valid. Only the combined result is wrong. A typical sequence:

14:02  Agent A starts refactoring auth.ts — half-finished edits sit uncommitted in the tree
14:03  Agent B (same folder) runs git switch feat/search — git swaps every file to that branch's snapshot and carries A's uncommitted edits along
14:05  Agent B runs git add -A && git commit — A's stray half-edits are now sealed inside B's "add search" commit
14:07  Agent A resumes; the files no longer match what it was editing, so it "helpfully repairs" them — reverting work B just committed
14:09  both agents report success. The history is a shuffle of two tasks; neither is complete; no error was ever raised

Variants of the same disease, all from our own logs: a branch switch yanking files out from under a process that was reading them (worse when a dev server runs from that working tree — it silently starts serving the other branch's code); two package installs racing on one lockfile; one agent running the test suite while another mutates the fixtures it's reading. Different symptoms, one cause: two writers, one working tree.

The fix is structural, not behavioral: give every concurrent writer its own working tree — a separate worktree or a separate clone — or don't let them be concurrent at all (queue them). Locks made of prose do not survive contact with a machine that reads instructions statistically.

Working with coding agents: the method

The material above condenses into an operating loop that works with any capable coding agent. Each step notes how TermRoam automates it; the method stands on its own.

Standing rules to give any agent

Commit these into whatever instruction file your agent reads. They are the distilled, non-negotiable subset of everything above (and they're what TermRoam boxes ship by default):

1. One task step = one commit, pushed immediately.
2. Never force-push. Never rewrite pushed history. Never use --no-verify.
3. Never kill servers, tmux sessions, or processes you did not start.
4. On merge conflict: STOP and report. Never resolve by discarding either side.
5. Never commit secrets or .env files.
6. "Done" requires proof: `git log origin/main..HEAD` prints nothing, and the tests named in the step pass.

How the discipline scales

• One agent, one repo: run the loop above by hand. The verification ritual (step 7) is the part humans skip — don't.
• Two or three agents: a worktree or repo per agent, and the ritual after every completion. This is where "it said complete" starts silently diverging from "it landed."
• A fleet: humans cannot verify at machine rate. Every convention above must become a machine-checked invariant — which is the product below.

How TermRoam implements this

TermRoam is a dedicated always-on server for coding agents. Its execute workflow implements the method above — and builds most of TermRoam itself with it:

• Specs (PRDs) with machine review. You write the checklist; a validator enforces commit-sized, verifiable steps before execution is possible. Chains of specs form the queue — a built-in merge queue with no extra service.
• Resident loops. One agent loop per repo works step-by-step: implement, test, commit, push, check the box, repeat. Provider cascade (Codex → Claude → others) survives quota exhaustion.
• A resident manager agent. An always-on overseer watches every loop: chain ETAs with confidence, failure triage from a playbook, velocity-correction memory that improves its own estimates.
• Guards. The main-detach guard clears the worktree trap before every auto-merge; conflicts halt the chain loudly; provider-limit output stops restart loops instead of hammering APIs.
• Invariants checked forever. The watcher continuously proves complete ⇒ on origin/main (UNMERGED badge otherwise), rescues dirty orphaned worktrees to pushed rescue/* branches, and reconciles drifted statuses.
• Built-in skills. Every box ships agent-readable skill files — the execute method, the deploy pipeline, the terminal substrate — so any agent you run arrives already knowing the house rules. The playbook above isn't documentation about the system; it's what the agents themselves read.

The pipeline, end to end

What we haven't covered yet (an audit we maintain)

This audit tracks what we actually run. Researching this page closed three rows. Green is machine-enforced, amber is partial, red is open:

The rows that silently destroy finished work went green first; CI and rollback pins went green while writing this page. What remains is identity and disaster recovery. If you are building your own setup, work the list top to bottom. TermRoam ships with the green rows in place.