Quintet Headless Worktrees

Drive several coding-agent CLIs as one-shot, non-interactive processes (codex exec, gemini -p, copilot -p), each confined to its own git worktree, then verify and merge their commits. The orchestrator (you) decomposes, dispatches, reviews, and integrates; the worker CLIs spend their own provider's tokens doing the work.

When to use this vs. the alternatives

• This skill — you want agents to write code or produce review artifacts in parallel, reliably, with file-level isolation, and you do not want to babysit interactive REPLs. Headless exec avoids the single biggest flake source of REPL teams: the warmup-swallow (the first task sent to a cold interactive CLI is often eaten).
• quintet-team-runtime — long-lived interactive tmux workers you steer over time.
• quintet-fleet-dispatch — one-shot opinions/reviews, no files written.

The deciding question: do agents mutate files in parallel and need isolation + clean merges? If yes, this skill.

🚀 First-Class CLI Usage (quintet worktrees)

Quintet provides an automated, first-class command that handles worktree creation, headless dispatch, tmux session isolation, and clean branch merging automatically:

QBIN="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/bin/quintet}"
[ -n "$QBIN" ] && [ -x "$QBIN" ] || QBIN="$(command -v quintet 2>/dev/null || echo quintet)"

# 1. Start headless worktree dispatch
"$QBIN" worktrees 2:codex:implementer,1:claude:implementer "build auth module" \
    --name auth-feat \
    --tasks "implement JWT in src/auth/||add unit tests in tests/auth/"

# 2. Check worker status & modified files
"$QBIN" worktrees status auth-feat

# 3. Merge completed branches into an integration branch and clean up
"$QBIN" worktrees merge auth-feat --branch feat/auth-integrated

# Abort and clean up in case of failure
"$QBIN" worktrees abort auth-feat

The core model

base commit ── wt1 (agent A) ─┐
            ── wt2 (agent B) ─┤  octopus-merge → integration branch → verify → push
            ── wt3 (agent C) ─┘

One worktree per work package, partitioned by disjoint file ownership so branches never touch the same file. That single design choice is what makes parallel agents produce clean merges instead of conflict soup. Cross-cutting files that no package owns (a shared config, a site-wide token) are the orchestrator's to edit during integration — assign them to nobody and a holistic review will later flag the gap.

Primitive 1 — Headless invocation (per-CLI)

Non-interactive mode is the reliability win. Each CLI has an auto-approve flag; without it the process blocks forever waiting for a confirmation it can't receive.

codex exec reads the prompt from a positional arg, from stdin via -, or piped. agy/claude/copilot take the prompt on -p and run in the current directory (so cd into the worktree, or for codex use -C <dir>).

Tmux Execution for Worktree Dispatches (Default Pattern)

When dispatching parallel worktree agents, launch each worker into its own window inside a dedicated detached tmux session. Set remain-on-exit on so a finished or crashed worker keeps its pane, and tee the output to a log in the worktree so it survives:

sess="quintet-worktrees-$(date +%s)"
tmux new-session -d -s "$sess" -c "$REPO" -n "leader"
tmux set-option -w -t "=$sess:=leader" remain-on-exit on
# Log visibility for the human user
echo "Worktree session active: tmux attach -t $sess"

# One window per worktree worker (exact targets: "=session")
tmux new-window -t "=$sess" -n "wt1-codex" -c "$WT1" \
  "codex exec -C '$WT1' -s workspace-write 'Read ./.brief.txt and follow it exactly.' 2>&1 | tee '$WT1/.agent.log'"
tmux set-option -w -t "=$sess:=wt1-codex" remain-on-exit on
tmux new-window -t "=$sess" -n "wt2-agy" -c "$WT2" \
  "agy -p 'Read ./.brief.txt and follow it exactly.' --dangerously-skip-permissions 2>&1 | tee '$WT2/.agent.log'"
tmux set-option -w -t "=$sess:=wt2-agy" remain-on-exit on

Add .agent.log and .brief.txt to the repo's .git/info/exclude. remain-on-exit is set right after the window is created, so a worker that dies within milliseconds can still lose its pane. For a hard guarantee, create the window on sleep 86400, set the option, then tmux respawn-pane -k -t "=$sess:=wt1-codex" "<command>" (this is what quintet team does).

No-tmux fallback: if tmux is missing or errors, run each worker as a background subshell with its output captured:

( cd "$WT1" && codex exec -C "$WT1" -s workspace-write 'Read ./.brief.txt and follow it exactly.' ) > "$WT1/.agent.log" 2>&1 &

Then wait and read each .agent.log.

Primitive 2 — Worktree setup (and the symlink trap)

git worktree add -b <branch> <dir> <base>
ln -s "$REPO/node_modules" "<dir>/node_modules"   # share deps; never reinstall
cp "$REPO/.env" "<dir>/.env"                       # gitignored secrets the build needs

Tell every agent "do not run npm install — node_modules is a symlink", or a sandboxed install will either fail or duplicate hundreds of MB per worktree.

The trap: .gitignore with node_modules/ (trailing slash) matches a directory, not a symlink named node_modules. So git add -A will stage the symlink into the commit, and merging it later creates a self-referential tracked symlink that collides with the real dir on checkout. Two defenses, use both:

• Instruct agents to stage explicit paths only (git add src/foo.ts), never git add -A/..
• Add node_modules (no slash) to the repo's .git/info/exclude.

After every agent finishes, verify the commit touched only owned files and amend out any leak.

Primitive 3 — The brief-file pattern (quoting hazard)

Real task briefs contain quotes, backticks, <>, $ — interpolating them into a shell -p "..." arg corrupts the command or triggers command substitution. Don't pass the brief on the command line. Write it to a file inside the worktree and give a tiny literal prompt:

cp brief.txt "<dir>/.brief.txt"            # exclude it from git too
codex exec -C "<dir>" -s workspace-write "Read ./.brief.txt and follow it exactly."

The CLI opens the file with its own read tool. Zero shell-escaping risk, and the brief can be arbitrarily long/complex.

Primitive 4 — Sandbox & commit gotchas (codex)

• Avoid --dangerously-bypass-approvals-and-sandbox. A safety classifier (and good sense) will block it. Use sandboxed write instead: -s workspace-write -c sandbox_workspace_write.network_access=true — confined to the worktree, but with network for build-time fetches. A blanket "I approve everything" from the user does not override the bypass block; sandboxed mode is what actually runs.
• Linked-worktree commit fails with EROFS / index.lock: Read-only file system. A linked worktree's git index lives in the main repo's .git/worktrees/<name>/, which is outside the worktree sandbox. So a sandboxed codex can edit files and run the build, but cannot git commit. Plan for it: the agent's edits land uncommitted in the working tree — the orchestrator (unsandboxed) builds, scans, and commits them. gemini --yolo / copilot --allow-all are not filesystem-sandboxed this way and commit fine.

Primitive 5 — Review-then-fix, on the worker's tokens

The point of external CLIs is token distribution: keep the orchestrator (your own model) for coordination/verification, and push review and the resulting fixes onto the provider CLIs. A review that only reports, then makes the orchestrator implement, defeats the purpose.

• Read-only review still needs workspace-write (the agent writes its report file); instruct "modify no source; write findings to ./REPORT.md."
• Run independent holistic passes from different model CLIs over the integrated tree — they catch cross-file inconsistencies single-package reviews structurally can't (e.g., the one file nobody owned).
• Triage findings against scope. Fix in-scope a11y/security/correctness; defer pre-existing, out-of-scope items rather than scope-creeping.

Primitive 6 — Concurrency hazards

• Two CLIs building in the same directory corrupt dist/. Either give each its own worktree, or pre-build once yourself and tell reviewers "a build already exists in ./dist; do not rebuild."
• Launch independent agents as parallel background jobs. One denied/blocked launch in a batch can cancel its siblings — isolate a risky launch (e.g. an untested flag) into its own probe first.

Primitive 7 — Integration & verification

• Merge disjoint-file branches with an octopus merge (git merge b1 b2 b3 ...); disjoint files → no conflicts.
• Never trust a worker's "exit 0." For every branch verify, in order: (1) commit scope = owned files only; (2) no node_modules/brief/secret leak in the diff; (3) npm run build green on the integrated tree; (4) grep the build output for secret values (build-time secrets must not reach client bundles).
• Reject environment-specific patches an agent adds to make its sandbox pass (e.g., redirecting cache dirs) — those are slop, not improvements. Commit the real fix, discard the workaround.

Primitive 8 — Secret hygiene

CLI tools that load env (e.g. netlify env:import) often echo the values back to stdout — a leak into your transcript/logs. Pipe through a mask, or prefer file-based imports that don't print values, and if a secret does surface, tell the user to rotate it.

Failure-mode quick reference