# Create Worktree > Use whenever the user asks to create a worktree for a task (e.g. "create a worktree for X", "spin up a worktree", "make a worktree for FRA-1234"). Creates the worktree via herdr, runs repo setup, splits three even panes (worker agent, Hunk review, user shell), and hands the agent the task context. Accepts `--agent ` to choose the worker (claude, codex, gemini, ...); defaults to the agent running the skill. - Skill: `vigneshwerv/create-worktree` (Agent Skill) - Install (CLI): `npx skillmds@latest add vigneshwerv/create-worktree` - Raw SKILL.md: https://api.skillmd.com/api/skills/vigneshwerv/create-worktree/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: vigneshwerv (https://skillmd.com/u/vigneshwerv) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/vigneshwerv/create-worktree --- # Create a worktree for a task Create worktrees with **herdr**, never with raw `git worktree add`. Requires `HERDR_ENV=1`; if herdr is unavailable, stop and tell the user instead of falling back to git. ## 1. Determine the branch name, task context, and worker agent - **Worker agent kind**: if the arguments include `--agent `, use that kind and drop the flag from the task text. Otherwise use the kind of the agent executing this skill (Claude Code is `claude`, Codex is `codex`). If that cannot be determined, use `codex`. The kind must be one herdr supports; check with `herdr agent start --help` if unsure. - **Linear task** (the user names or links an issue like FRA-1234): fetch the issue with the Linear MCP `get_issue` tool. Use Linear's generated branch name (the issue's `gitBranchName`) — do not invent your own variant. Keep the issue title, description, and URL for the agent kickoff prompt in step 5. - **No Linear task**: use a short kebab-case slug describing the task, no prefix (e.g. `fix-balance-drift`). The user's own task description is the context for step 5. ## 2. Create the worktree From the repo the task belongs to (default: the current repo), base new branches on that repo's main development branch — for `workspaces` that is `dev`, not `main`. ```bash herdr worktree create --branch --base dev --label "" ``` The command returns JSON — read the worktree path and the root pane ID (`.result.root_pane.pane_id`) from the response rather than predicting them. ## 3. Run repo setup (bootstrap) For the `workspaces` repo, run the setup script in the worktree's root pane so progress is visible in the new workspace, and wait on a completion marker: ```bash herdr pane run "./setup_worktree.sh && echo BOOTSTRAP_DONE" herdr pane wait-output --match "BOOTSTRAP_DONE" --timeout 600000 ``` - Defaults are `--stage=dev --region=us-east-1`; pass `--stage=` / `--region=` only if the user asked for a specific stage or region (e.g. their personal stage). - The script runs `yarn`, `yarn prepare`, then `assume` + `aws sso login` + dashboard `yarn gen-env`. The AWS steps complete via the browser; if the wait times out, `herdr pane read --source recent-unwrapped --lines 60` to see where it stalled, tell the user, and let them finish it in that pane — do not retry blindly. For other repos, skip this step. ## 4. Split into three even panes: agent, Hunk, user Only after bootstrap completes, split the root pane into three vertical columns of equal width — agent on the left, the Hunk review TUI in the middle, the user's shell on the right. `--ratio` is the **left** side's share of the split being made, so thirds come out of `1/3` then `1/2`; no resizing afterwards: ```bash # root keeps the left third; the new pane takes the right two thirds herdr pane split --pane --direction right --ratio 0.3333 \ --cwd --no-focus # halve that two thirds: middle for Hunk, right for the user herdr pane split --pane --direction right --ratio 0.5 \ --cwd --no-focus ``` Read each new pane id from the command's JSON rather than predicting it, and confirm the result with `herdr pane layout --pane ` — the three `rect.width` values should match. If a layout ever needs correcting, `herdr pane resize --pane --direction left|right --amount ` adjusts one seam. Start Hunk in the middle pane, watching the worktree so it picks up the agent's edits as they land: ```bash herdr pane run "hunk diff --watch" ``` An empty worktree is fine — Hunk sits at zero files and fills in. Confirm the session is live with `hunk session list`; that session is what makes the agent's review notes in step 5 possible. Then start the worker agent of the chosen kind in the left (root) pane with a name derived from the task (must match `[a-z][a-z0-9_-]{0,31}`, e.g. `fra-7545`): ```bash herdr agent start --kind --pane ``` Kind-specific notes. Native agent arguments go after `--`: - `claude`: after it starts, enable remote control mode by sending `/rc`. - `codex`: start it with `--approve-for-me`, so approval requests are reviewed automatically inside the workspace-write sandbox instead of blocking on the user: ```bash herdr agent start --kind codex --pane -- --approve-for-me ``` Other kinds need nothing extra. ## 5. Kick off the agent with task context Send one kickoff prompt via `herdr agent prompt "..."` (no `--wait` — the task will outlive any reasonable wait). The prompt must be self-contained; the agent has none of your conversation context. Include: - The task: Linear issue ID, title, URL, and the full description (or the user's task description if no Linear issue). - The branch name it is already on, and that it is in a fresh worktree at ``. - That bootstrap is done: dependencies installed, SST stage/region set, `dashboard/.env` generated — no setup needed. - Anything task-relevant the user said when asking for the worktree (constraints, hints, files to look at). - What to do: implement the task, run the repo's verification (`yarn typecheck-all`, relevant tests), and stop before committing unless told otherwise. - How to leave comments for the user: **Hunk**, per the rules below. Spell them out in the prompt — the agent will not have read this skill. ### Leaving comments for the user with Hunk The agent reports what it did in prose, but anything that is *about a specific line* belongs on that line. Instruct the agent to leave those as Hunk review notes once the work is verified: ```bash # one note hunk session comment add --repo --file --new-line \ --summary "" --rationale "" # several notes at once, validated as a batch printf '%s\n' '{"comments":[{"filePath":"...","newLine":12,"summary":"..."}]}' \ | hunk session comment apply --repo --stdin ``` Rules to pass on: - **Never run `hunk diff`, `hunk show`, or any other interactive Hunk command.** The TUI in the middle pane is the user's; the agent only drives that session through `hunk session *`. - The session from step 4 is already live on the worktree, so `--repo ` resolves it. If `hunk session list` shows no match — the user closed it — say so in the final report and ask them to run `hunk diff` again, rather than dropping the notes. - Comment on what the user would not spot alone — a decision worth second-guessing, a risk, a deliberate omission, a follow-up. Not every hunk, and never a restatement of the diff. - Prefer one `comment apply` batch when several notes are already in hand. - `--summary` is a real sentence; it is what `comment list` shows and the fallback everywhere else. ## 6. Report Tell the user: branch name, worktree path, bootstrap status, the agent's kind, name and pane (left), that Hunk is watching the worktree in the middle pane and is where the agent's review notes will land, and that the right pane is their own shell. Do not implement the task yourself — the spawned agent owns it.