Run work in isolated Git worktrees

AFK can run sessions and subagents in separate Git worktrees so parallel edits and tests do not collide with your main checkout. Use afk i --worktree for a whole interactive session or isolation: "worktree" on an agent dispatch for one child. Review preserved changes before cleaning up checkouts or branches.

afk i --worktree

Choose the base and branch nameCopy Anchor Link

Interactive --worktree fetches and starts from the remote default branch unless you set --worktree-base or AFK_WORKTREE_BASE. Set AFK_WORKTREE_BASE=HEAD to start from local HEAD. A branch uses the afk/ prefix by default; AFK_WORKTREE_BRANCH_PREFIX changes it. Interactive branches can be named from your first message when AFK_WORKTREE_AUTONAME=1 (the default). The worktree model tool's create action, by contrast, defaults its base to HEAD.

Decide what happens on exitCopy Anchor Link

After a clean interactive --worktree session, the REPL asks whether to keep the checkout and enter it, or delete the checkout and branch. A kept checkout is locked against automatic sweeping. --worktree-on-exit keep|remove|ask, AFK_WORKTREE_ON_EXIT, and interactive.worktreeOnExit set this policy; the CLI flag takes precedence. A dirty checkout is preserved rather than discarded. If the prompt cannot be displayed under the ask policy, the checkout is preserved without a permanent lock and remains eligible for later sweeping. A zero-turn session has no work to preserve. This quit-time deletion of an interactive branch is different from the model worktree tool's remove, which preserves its branch ref.

Install dependencies in newly managed worktreesCopy Anchor Link

Agent-created worktrees do not share ignored files such as node_modules with the main checkout. Commit .afk/worktree-setup.json in a trusted repository to run setup after creation through the worktree model tool, an isolated agent, or an isolated compose node:

{
  "commands": ["pnpm install --frozen-lockfile"],
  "timeoutMs": 300000
}

Commands run in order from the new worktree and stop on first failure. The optional timeoutMs defaults to five minutes per command. The file is read from the worktree's base commit. Creation still succeeds if setup fails, times out, or the declaration is invalid; the response includes a notice. The interactive afk i --worktree launcher does not run this setup, so run installation yourself or ask the agent to do it. Setup scripts run as your user, so only enable this in trusted repositories.

Dispatch a child into its own checkoutCopy Anchor Link

Ask AFK to use the agent tool with these parameters:

{"prompt":"Implement and test the parser fix. Report the branch and verification.","isolation":"worktree","mode":"background"}

Isolation creates a managed branch under .afk-worktrees/ from the dispatching session's HEAD, confines the child there, and tries to remove its checkout after completion. A dirty checkout, commits ahead of base, or non-rebuildable ignored files cause it to be preserved and locked instead. mode: "background" returns a job ID while the child works; the result arrives automatically when it finishes. You cannot combine worktree isolation with cwd or writeRoots; you can still grant readRoots. Read-only named agents do not need this isolation and are unaffected.

Alternatively, call the worktree tool's create action with name and optional base, then pass its returned absolute path as the child's cwd. Managed creation writes .afk-worktree-meta.json; raw git worktree add does not, and may be treated as an orphan by the sweeper.

Inspect and clean up checkoutsCopy Anchor Link

afk worktree list
afk worktree prune

Both are dry runs. afk worktree prune --apply executes eligible removals; use --max-age-days-clean and --max-age-days-dirty to adjust thresholds. Defaults are 14 days for clean and 30 days for dirty, with configuration and environment overrides. empty, dead-owner, and orphaned checkouts may be reaped; stale dirty work is warned about and preserved. A stale clean checkout with commits ahead is also preserved and warned about, not silently deleted. A lock protects a checkout from age-based pruning. AFK_WORKTREE_BOOT_PRUNE=1 enables startup pruning by the daemon; AFK_WORKTREE_PRUNE_DISABLE=1 disables the sweep.

The worktree model tool supports list, keep with a human-readable reason, release, and remove. Its remove preserves the branch ref and refuses dirty, locked, commits-ahead, or non-rebuildable ignored-file checkouts unless explicitly forced. Release a lock before removal. force: true can destroy uncommitted or ignored local files, so inspect them first. A checkout saved for commits ahead can be auto-unlocked by a later sweep once all commits reach upstream; dirty checkouts can be auto-unlocked once clean. Explicit keep-on-exit and ignored-local-state locks are not auto-unlocked.

Prune remote branches separatelyCopy Anchor Link

afk worktree prune removes eligible checkouts, not stale remote refs. To inspect afk/* branches on origin against main and their pull request status:

afk branch prune

This is a dry run. afk branch prune --execute deletes branches classified as safe; that is a remote operation, so review its table before running it. Open pull requests and detected unmerged commits are preserved. The classifier treats an unavailable GitHub CLI as "no PR" and a failed commit-ahead probe as zero ahead, so do not treat its output as proof that every candidate is safe. --remote, --base, and --prefix change the default target. To compare several task attempts rather than delegating one isolated child, see the farm guide.

RelatedCopy Anchor Link