Why AI Coding Agents Belong in Git Worktrees

AI coding agents should work in git worktrees because parallel work needs isolation. A worktree gives each agent its own checkout, its own diff, and a place where the human operator can inspect the actual files instead of relying on a chat summary.

That is the core design of Kadro Teams. Agents do not share one mutable working directory. They operate in separate worktrees, write durable state into a shared notebook, and coordinate through a small MCP bridge.

The failure mode: one agent, one checkout, one long thread

The default AI coding setup starts simple: open a chat, ask for a change, accept a diff, run tests, repeat. It works until the task needs more than one line of thought. Then the same agent is reading, planning, coding, reviewing, and explaining its own mistakes in one continuous history.

The filesystem has the same problem. If multiple agent sessions touch one checkout, they can overwrite each other, invalidate each other’s assumptions, or make the final diff impossible to reason about. Parallelism without isolation creates review debt.

The worktree model

A git worktree is a separate working directory attached to the same repository. It can have its own branch, files, and running processes while still being connected to the same repo history.

For agents, that gives a clean boundary:

• The builder can edit and run tests without touching the scout.
• The reviewer can inspect a diff without mutating the builder’s state.
• The architect can prototype or compare approaches without polluting main.
• The operator can open any worktree in normal developer tools.

Worktrees make agent work visible to git. That is what makes the work easier to trust.

Roles make the worktree useful

Isolation alone is not enough. Kadro Teams pairs worktrees with built-in roles so each agent has a job:

• scout maps the codebase, finds constraints, and brings context back before implementation starts.
• architect turns the mission into a plan and decides what should not be built.
• builder writes code in its own worktree.
• reviewer reads the diff and pushes back before the operator accepts the work.

The useful loop is scout to architect to builder to reviewer, with the operator deciding when the mission is done.

The shared notebook keeps memory out of the chat

Kadro Teams use an append-only NDJSON notebook as durable mission state. Decisions, findings, lifecycle events, handoffs, and review notes land in a file the dashboard can read and the agents can share.

This is deliberately boring infrastructure. NDJSON is grep-able, diff-able, and stream-friendly. Append-only history prevents agents from rewriting what happened. A shared notebook keeps coordination from disappearing inside private context windows.

The MCP bridge gives agents a controlled way to coordinate

Multi-agent work needs more than adjacent terminals. Agents need a controlled way to ask for assignments, call another agent, append a note, read mission state, wait for a signal, and mark work complete.

Kadro exposes that coordination through the MCP bridge. The goal is not to make agents autonomous forever. The goal is to make their coordination observable enough that the operator can intervene.

What review looks like with worktrees

In Kadro ADE, the dashboard can show per-agent worktree paths, read-only diffs against the base branch, changed files, commits, notebook events, and terminal state. Review becomes a continuous workflow instead of a final prompt that asks, "did you finish?"

That changes the quality of human oversight. You can inspect the builder’s worktree, compare it to the reviewer’s notes, restart a stuck agent, or nudge the crew with a tighter instruction while the mission is still active.

When to use agent worktrees

Use worktree-based agents when a task has parallel investigation, implementation, and review. Use a smaller workflow when the job is a simple edit. More agents are not automatically better; clearer roles and cleaner isolation are the point.

Download Kadro ADE if you want to run this model locally on macOS with Claude Code, Codex, Gemini, shell panes, and Teams in one visible workspace.