Worktrees and parallel agents

For context inheritance, model selection, messages, cancellation, and result verification, see the agent lifecycle guide. This page focuses on checkout isolation and worktree retention.

Start an isolated checkout

From a Git repository:

agent-cli --worktree

Or use /worktree to start a fresh session in a new managed worktree. /copy-path copies the active worktree path.

By default, managed worktrees fetch and branch from the selected remote's latest default commit, not from your current uncommitted changes. Repositories without a remote use local HEAD.

The remote is chosen from the current branch's configured remote, then upstream, origin, or the repository's sole remote. A fetch failure aborts creation instead of silently using a stale commit.

To disable fetching, merge this setting into ~/.haskell-agent/config.json:

{
  "version": 1,
  "worktree": {
    "fetchLatestUpstream": false
  }
}

The policy applies to initial worktrees, /worktree, and subagent worktrees.

Delegate independent tasks

Ask for explicit boundaries:

Use one agent to inspect the parser tests and another to review the public API.
Neither should edit files. Combine their findings before proposing changes.

Use /agents to inspect agent activity. Configure the concurrent subagent cap:

/agents limit 3

Or set it at startup:

agent-cli --max-concurrent-agents 3

Separate research tasks are a good starting point. If multiple agents must edit, assign non-overlapping ownership or ask for separate worktrees. Shared checkouts do not automatically prevent conflicting edits.

Expected result for the research example: two scoped findings reports and a combined recommendation, with no file edits. Inspect /agents while work is running. If both agents are investigating the same files for the same purpose, ask the coordinating agent to narrow their assignments rather than increasing the concurrency limit.

Have the parser reviewer report test gaps only. Have the API reviewer report compatibility risks only. Combine both reports without editing files.

Branch the conversation

/fork creates a peer session from the current chat. Explicitly request checkout isolation when needed:

/fork --worktree Investigate an alternative implementation.

Without an isolation flag, the dialog initially selects “Use a new worktree”; “Share current workspace” is the other choice. Escape cancels. Use --no-worktree only when both conversations should see the same files. The fork prints a new session ID and switches into that peer conversation; an optional directive becomes its starting instruction.

1. Record the original ID with /session before forking.
2. Try the alternative in the peer; inspect its diff and test results.
3. Return with /resume ORIGINAL_ID and summarize the alternative.
4. For an isolated checkout, review and deliberately integrate the desired commits or changes. Forking does not automatically merge them. For a shared checkout, the files have already changed for both conversations: avoid overlapping edits and inspect the current diff before continuing.

Review how changes should be integrated before asking agents to merge or publish them.

Retention and recovery

Managed worktrees are collected only when clean, incorporated into another branch, and inactive for at least 24 hours, subject to additional safety checks. Dirty and unmerged work does not expire simply because it is old.

Preview cleanup without removing checkouts:

agent-cli worktree gc --dry-run

Protect a checkout while using it outside the agent:

agent-cli worktree protect /absolute/path/to/managed/worktree

Resuming a collected session restores its checkout. Recognized ignored build and cache directories are disposable and are not restored. Recovery depends on the original shared Git repository and local worktree registry; it is not a substitute for backups.

Choose and repair the checkout base

Do not combine --worktree with --resume. Run from a Git repository, or set --cwd to one. A remote fetch failure aborts creation instead of silently using stale commits. Fix authentication, connectivity, or remote configuration before retrying.

Default-branch discovery caches refs/remotes/REMOTE/HEAD. The server is queried when this reference is absent or invalid, or the cached branch no longer exists. If the remote changes its default but keeps the old branch, refresh the cache explicitly. For a new default of main on origin:

git fetch origin refs/heads/main:refs/remotes/origin/main &&
git remote set-head origin --auto

Substitute your actual remote and branch. Fetch first: set-head --auto requires the remote-tracking reference, which isolated agent fetches do not create.

Understand collection decisions

Inactivity means saved-session activity, not commit age or merge time. Automatic adoption requires managed-root location, reciprocal linked-Git metadata, and saved-session ownership evidence. Archived sessions and sessions in checkout subdirectories contribute activity. Missing or ambiguous evidence retains the checkout; adoption does not reset an old checkout's clock to today.

agent-cli worktree enroll PATH explicitly enrolls a checkout and starts its inactivity clock now. worktree protect PATH prevents collection; worktree unprotect PATH removes that protection. A saved conversation alone does not protect a checkout forever.

Local incorporation proof requires exact ancestry into another surviving branch, excluding the checkout's own branch and upstream. An equal-tip copy alone is not enough except for the resolved default branch. Squash/rebase merges require authenticated GitHub evidence identifying a merged PR at the exact checkout HEAD, a locally available reachable merge commit, and preservation of changed paths' final content and modes. Ambiguity retains the checkout. GC does not fetch, so cached references can miss a recent merge.

Explicitly ignored known caches such as node_modules, dist-newstyle, and .venv are disposable, as is an ignored result symlink directly into the Nix store. Known agent settings and generated OpenAI files are disposable only when byte-identical regular copies remain in the primary checkout. Other ignored data, including .env and local databases, prevents collection. Protect caches containing irreplaceable data.

Use worktree gc --dry-run first. It reports simulated adoption, retained reasons, eligibility, and gross apparent checkout bytes without writing registry entries or snapshots. The estimate is not net freed disk space: filesystem sharing and snapshot overhead differ. Database failures defer adoption rather than guessing from directory age. Failed and not-examined candidates are separate from deliberately retained ones.

Enroll an existing managed checkout

Enrollment is explicit consent to the retention policy, including the ignored-file exclusion; it is not a way to enroll an arbitrary repository directory. Pass the managed checkout root, not a subdirectory or a path containing traversal components. The checkout must be a genuine linked Git worktree under the managed root, with reciprocal Git metadata and no symlinked checkout/repository/administration paths. The primary checkout is rejected.

Run agent-cli worktree enroll /absolute/managed/checkout only after inspecting the target. First enrollment starts its inactivity clock now and creates an unprotected record. Re-enrollment of the same identity preserves the existing record; it is not a request to reset that clock. Changed repository identity, broken metadata, or an active maintenance/session lease is an error. Close the owning session or repair the actual Git metadata before retrying; do not remove lease files to bypass an active owner.

Restore a collected checkout

agent-cli worktree restore /absolute/path/to/managed/worktree

Restoration recreates a detached HEAD and does not reset a branch that moved since collection. It refuses an existing destination directory. An interrupted restore that leaves a directory requires manual inspection and recovery rather than overwriting it. Retained Git recovery references preserve historical commits, including checkout reflogs and recovery state; disposable caches are not restored.

Keep the original shared repository and ~/.haskell-agent/worktrees/.registry. Neither local snapshots nor conversation export is an off-machine backup. Active leases, unsupported Git states, active merge/rebase operations, incomplete snapshots, or detected concurrent edits block deletion. External editors do not participate in leases: protect their checkouts, and stop pre-upgrade agent processes before explicit collection.