Worktrees and isolation

What's a worktree

A Git worktree is an extra working directory attached to the same repository: its own checked-out branch and files, sharing the repo's history. Anymo creates one per coding job under a sibling directory, never inside your checkout:

/path/to/repo                          # your checkout, untouched
/path/to/repo.anymo-worktrees/
├── jobs/coder-a/                      # one isolated worktree per job
├── jobs/coder-b/
└── state/                             # harness metadata

The harness never clones your repository, and it never modifies the main checkout: not for worktree creation, command execution, patch application, review, or cleanup. You keep working normally while any number of jobs run beside you.

Why this matters

• Parallelism without collisions. Five agents fixing five bugs each get their own working directory and branch; none of them can see, let alone break, the others' work in progress or yours.
• Everything is a reviewable diff. A job's output is a patch set, not mutations scattered through your tree. You review it like a pull request.
• Mistakes are disposable. A bad job's worktree is deleted; nothing to untangle from your checkout.

The job lifecycle

1. A job gets a worktree

   When a coding swarm plans work, coder, tester, reviewer, and verifier lanes receive isolated worktree instructions by default; each agent gets or creates a WorktreeJob branched from your chosen base.

2. Changes are applied transactionally

   The agent's patches apply atomically inside the job worktree. If a later patch fails, earlier ones roll back; a job is never left half-applied.

3. Commands run inside the worktree

   Tests, lints, and builds execute in the job's directory through approval-gated project commands, so a job proves its work where it made it.

4. Patch review

   The harness collects the Git diff, runs git diff --check, and checks for merge conflicts against the base branch, producing a PatchReview with findings and test evidence.

5. Integration decision

   You accept or reject. Conflicts, diff findings, and command gates remain approval points; accepted work integrates from the job branch. Nothing merges without a human decision.

Project commands

Repositories define their command gates in anymo.project.toml; the harness also ships safe defaults for test, lint, and build:

[commands.test]
argv = ["cargo", "test", "--workspace"]
approval_required = true

[commands.lint]
argv = ["cargo", "clippy", "--all-targets", "--all-features"]
approval_required = true

This is also how "just say test" works: you ask in chat, the agent invokes the project's test command, and the approval prompt is the gate. Commands run directly without a shell, programs must be bare executable names, and all default commands require approval because they execute local processes.

Driving it directly

Everything the app does with worktrees is scriptable:

anymo project doctor --repo .                       # harness readiness
anymo worktree create coder-a --repo . --base main  # create a job
anymo job run coder-a --repo . --command test --approve
anymo patch review coder-a --repo .                 # diff, checks, conflicts
anymo worktree clean coder-a --repo . --remove-branch

Lighter isolation: transactional overlays

Not every job needs Git. For general swarm work, workers run in transaction mode: an isolated overlay against a workspace snapshot where file.write stages text patches instead of writing shared files and binary outputs become artifacts. A verifier computes patch sets and conflicts, and a conservative merge policy applies: low-risk, non-conflicting creates merge automatically; overwrites, large or binary changes, and conflicts require your approval; path and symlink escapes are denied. Merges roll back cleanly on failure. A future git-worktree backend can replace the overlay store without changing any of these semantics.

External agents get the same containment

The Runtime Bridge runs other vendors' CLI agents inside managed worktrees too: output is captured as events, the diff is harvested, tests run, and a patch review gates integration, so a third-party agent gets the sandbox-and-review guarantee even when it cannot ask for per-action approval.

Frequently asked questions

Can a job open a pull request for me?

Not automatically, by design. The harness keeps PR-ready branches after cleanup (unless you pass --remove-branch); a future gh pr create path will activate only when GitHub's CLI is installed, authenticated, and explicitly configured by you, behind a final command gate.

Does my repo need to be clean?

The harness detects repository state with anymo project doctor. Your checkout's dirtiness does not block jobs, because jobs never touch it; worktrees branch from the base ref you choose.

Do worktrees eat disk?

They share the repository's object store, so each job costs roughly a working copy of changed files. anymo worktree clean removes a job's tree when you are done.