Tour: one repo, many hands with worktrees

A single checkout serves one pair of hands. Add an agent or several and they fight over the same index, HEAD, and working tree. madtea worktree makes isolated per-task trees the paved road.

Full reference: cli-git.md - worktrees and madt_worktrees for the MCP side.

The pattern

madtea worktree add .worktrees/rate-limiter feat/rate-limiter   # own tree, own branch
# ... agent works in .worktrees/rate-limiter ...
madtea finish --branch feat/rate-limiter                        # finish by name; no checkout switch
madtea worktree remove .worktrees/rate-limiter                  # clean up when done

Each task gets its own directory and its own branch. Parallel tasks never share an index, so they never race.

Why isolated worktrees matter for agents

Agents in a shared checkout fight over every git state: git add, git commit, and git checkout all touch the same index and HEAD. Two agents committing at the same time on the same checkout will interleave or overwrite each other’s staged files even on disjoint files. A per-agent worktree removes the contention entirely - each agent writes its own index with no coordination needed.

The MCP server’s tool descriptions assume multi-agent work: madt_commit and madt_add are designed to be called from a worktree path, and madt_worktrees action=status reports every tree’s state in one call.

Guarded remove

madtea worktree remove .worktrees/rate-limiter

If the worktree is dirty or locked, this refuses - there is no force override. You either commit or stash first, or - if the work is genuinely disposable - run git worktree remove <path> --force yourself in your own shell. madtea carries no way to force-discard a dirty tree.

Agent-only MCP actions

Agents driving worktrees over MCP get two extra actions via madt_worktrees:

• status - reports every tree’s branch, clean/dirty, and ahead/behind in one call.
• rebase - re-bases a worktree’s branch onto a fresh base while refusing to touch the primary checkout.

Both are agent-facing (the CLI has equivalents but the MCP actions are tuned for non-interactive calls).

Example: three agents in parallel

# Set up three worktrees before spawning agents
madtea worktree add .worktrees/auth     feat/auth
madtea worktree add .worktrees/ratelimit feat/ratelimit
madtea worktree add .worktrees/metrics  feat/metrics

# Each agent works in its own tree, commits, and reports done.
# Lead finishes each branch by name without switching checkouts:
madtea finish "feat: auth" --branch feat/auth --closes 101
madtea finish "feat: rate limiter" --branch feat/ratelimit --closes 102
madtea finish "feat: metrics" --branch feat/metrics --closes 103

# Clean up
madtea worktree remove .worktrees/auth
madtea worktree remove .worktrees/ratelimit
madtea worktree remove .worktrees/metrics

See tour-finish.md for the finish workflow. See tour-orchestrate.md for landing the batch after parallel work.

Part of the guides - madtea documentation.