Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs(skill): document parallel sub-Agent worktree pattern (#2600)

Maximilian Roos33db25618a86
diff --git a/docs/static/.well-known/agent-skills/index.json b/docs/static/.well-known/agent-skills/index.json
index 0089b26a7..3d492f3ed 100644
--- a/docs/static/.well-known/agent-skills/index.json
+++ b/docs/static/.well-known/agent-skills/index.json
@@ -6,7 +6,7 @@
"type": "skill-md",
"description": "Guidance for Worktrunk (the `wt` CLI) — git worktree management, hooks, and config. Load when editing .config/wt.toml or ~/.config/worktrunk/config.toml; adding, modifying, or debugging hooks (post-merge, post-start, pre-commit, pre-merge, post-switch, etc.); configuring commit message generation or command aliases; or troubleshooting wt behavior. Also answers general worktrunk/wt questions.",
"url": "./worktrunk/SKILL.md",
- "digest": "sha256:3ffa0c179f636b013238a47095d5699f7ccee1f90f1c62620f65ed78a0f2042c"
+ "digest": "sha256:473294af2b78d1cb14b9b87bf7799d6e2e755b238515ce214b9c5ff3c47699db"
}
]
}
diff --git a/skills/worktrunk/SKILL.md b/skills/worktrunk/SKILL.md
index ecc821598..0867ff16b 100644
--- a/skills/worktrunk/SKILL.md
+++ b/skills/worktrunk/SKILL.md
@@ -297,3 +297,22 @@ Example (Zellij, OpenCode):
zellij run -- wt switch --create fix-auth-bug -x 'opencode run' -- \
'The login session expires after 5 minutes. Find the session timeout config and extend it to 24 hours.'
```
+
+### Parallel sub-Agents (single Claude Code session)
+
+To spawn multiple sub-Agents that each work in their own worktree from one Claude Code session — no terminal multiplexer, no human in the other pane — pre-create each worktree from the parent and pass the path into the sub-Agent prompt:
+
+```bash
+wt switch --create <branch> --no-cd --no-hooks
+```
+
+Then call the `Agent` tool **without** `isolation: "worktree"`, naming the path in the prompt:
+
+```
+You are working in `/abs/path/to/worktrunk.<branch>` on branch `<branch>`.
+All edits must stay in that worktree.
+```
+
+`--no-cd` skips the shell-integration cd script the parent can't consume; `--no-hooks` is appropriate when each sub-Agent will run its own build/test step (e.g. `cargo run -- hook pre-merge --yes`) and you don't need post-start setup repeated per worktree.
+
+**Do not** use `Agent { isolation: "worktree" }` for this. Claude Code passes its internal agent ID as `name` to the `WorktreeCreate` hook, so `wt` creates the worktree as `worktrunk.agent-<id>` on a throwaway branch. If the sub-Agent then creates a feature branch on top, you end up with non-canonical paths, orphan branches, and post-start hooks fired against the wrong branch. Pre-creating with `wt switch --create` keeps path, branch, and hook target aligned.