Quintet Team Runtime

A team is a detached tmux session named quintet-<name>, one window per worker (plus a leader log window). Workers are interactive agent CLIs that receive a task via send-keys and then work autonomously in the shared cwd. State lives in ${QUINTET_STATE_DIR:-$PWD/.quintet}/teams/<name>/ (team.json, taskboard.md).

Attach to watch live: tmux attach -t quintet-<name> (detach with Ctrl-b d).

When to use

Use when you need several agent CLIs to do work in parallel — implementing, refactoring, testing, or auditing different parts of a repo at the same time. Don't use when you just want opinions or a review on one question; that one-shot, read-only case is skills/quintet-fleet-dispatch. The decision hinges on whether files get written (team) or not (fleet).

Inputs and outputs

• Input: a team spec (N:provider tokens), a shared goal, and one scoped subtask per worker.
• Output format: each worker produces real file edits in the shared cwd plus self-reported status lines on the taskboard. The orchestrator's job is to verify those artifacts and report what actually landed.

Usage

The lifecycle is four phases — launch, monitor, steer, tear down.

BIN="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/bin/quintet}"
[ -n "$BIN" ] && [ -x "$BIN" ] || BIN="$HOME/.gemini/config/plugins/quintet/bin/quintet"
[ -x "$BIN" ] || BIN="$HOME/.gemini/extensions/quintet/bin/quintet"
[ -x "$BIN" ] || BIN="$(command -v quintet 2>/dev/null || echo quintet)"

# 1. Launch (distinct subtask per worker, in spec order)
$BIN team 2:codex,1:agy,1:qwen "build the export feature" \
    --name export-feat --cwd /path/to/repo \
    --tasks "implement CSV serializer in src/export/||add unit tests in tests/export/||write docs in docs/export.md||audit edge cases and report to taskboard"

# 2. Monitor & Diagnose (poll; do not assume success)
$BIN team status export-feat
$BIN team doctor export-feat            # inspect worker panes & diagnose blocked confirmation modals
$BIN team capture export-feat            # all workers, last 40 lines each
$BIN team capture export-feat w1-codex 80

# 3. Steer a worker mid-flight
$BIN team send export-feat w3-agy "skip the legacy path; focus on v2 API"

# 4. Tear down when verified
$BIN team shutdown export-feat           # keep state
$BIN team shutdown export-feat --force   # purge state too
$BIN team list                           # all running quintet teams
$BIN prune --days 7                      # garbage-collect dead teams & aged debate logs

Workers are auto-named w<idx>-<provider>-<role> (or w<idx>-<provider> for stock); use these exact names for capture/send. Names are matched exactly: the old w1 shorthand no longer works (see team status <name>).

Subagent Worker Roles, Models & Extended Spec Syntax

Quintet supports assigning specialized subagent roles and target models using the extended spec syntax N:provider[:role][:model]:

# Explicit role & model assignment
$BIN team 1:codex:implementer:gpt-6.1-sol,1:agy:code-reviewer:gemini-3.1-pro-high,1:claude:security-auditor:sonnet "build auth feature"

# Mix of specialized roles, stock defaults, and custom models
$BIN team 1:codex:implementer,1:claude::haiku "build and verify" --effort high

Team and fleet also accept global flags --model <name> and --effort <level> (or environment overrides QUINTET_<P>_MODEL, QUINTET_<P>_EFFORT, QUINTET_MODEL, QUINTET_EFFORT).

Available expert roles (view via quintet roles or quintet roles <category>):

• Engineering: system-architect (arch), api-designer (api), implementer (impl), refactoring-specialist (refactor), code-reviewer (reviewer), test-engineer (test), debugger (debug), database-engineer (db), performance-engineer (perf), security-auditor (sec), devops-troubleshooter (devops), site-reliability-engineer (sre), technical-writer (docs).
• Design & Web: web-designer (webdesign), conversion-designer (cro), ui-designer (ui), design-system-architect (design-tokens), ux-architect (ux), accessibility-specialist (a11y), ux-researcher.
• Business: business-strategist (biz-strat), competitive-analyst, product-manager (pm), pricing-strategist (pricing).
• Marketing: brand-strategist (brand), copywriter (copy), technical-content-strategist (tech-marketer), growth-engineer (growth), seo-specialist (seo), launch-strategist (launch).
• Sales: sales-engineer (se), outbound-strategist (sdr), deal-strategist (closer), customer-success-lead (cs-lead).
• Philosophy: first-principles-analyst (first-principles), dialectical-challenger (devils-advocate), tech-ethicist (ethicist), unix-philosopher (minimalist).
• Legal: licensing-auditor, privacy-officer, policy-author.
• Operations: workflow-orchestrator (scrum-master), knowledge-architect.
• Education: learning-scientist, curriculum-architect, instructional-designer, metacognition-coach, inclusive-educator (udl-specialist), ai-tutor-architect (socratic-tutor).
• Baseline: stock (unprompted model default).

Pre-flight Auth Checks & Readiness Gates

Before creating any tmux sessions or panes, quintet team validates that every provider in the spec is installed and authenticated via quintet_provider_ready. If any provider is unready (missing CLI binary or none auth), startup halts immediately with diagnostic guidance (quintet doctor), preventing deadlocked workers. Auth detection is a heuristic (file and env-var presence only, values are never read): claude is none only with no ~/.claude/.credentials.json, no ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN/CLAUDE_CODE_OAUTH_TOKEN, no Bedrock/Vertex env, and not on macOS (keychain); agy is none without ~/.gemini/antigravity-cli/antigravity-oauth-token, ~/.gemini/oauth_creds.json, GEMINI_API_KEY or GOOGLE_API_KEY. quintet doctor shows an undeterminable result as unverified. A custom QUINTET_<P>_LAUNCH (or the legacy QUINTET_GEMINI_LAUNCH for agy) skips the check for that provider.

Bypass: Pass --skip-auth-check or set export QUINTET_SKIP_AUTH_CHECK=true to skip pre-flight gates (e.g. in test harnesses or custom shell stand-in workers).

Disabling MCP Servers (--no-mcp)

To prevent worker agents from loading extraneous host or global MCP servers that may trigger interactive confirmation modals or consume context:

• Pass --no-mcp to quintet team:

  $BIN team 1:codex,1:claude "refactor module" --no-mcp

• Or set export QUINTET_NO_MCP=true to disable MCP across all workers by default.

This maps to provider isolation flags (--strict-mcp-config for Claude, -c mcp_servers={} for Codex). It is partial for Copilot (--disable-builtin-mcps only: user, workspace and plugin MCP servers stay on) and unavailable for agy, qwen and OpenCode; quintet logs a WARN and records no_mcp_effective per worker in team.json.

Tiered Permission & Safety Mode (--safe)

By default, team workers launch with unattended autonomy flags (--permission-mode bypassPermissions for Claude, --yolo for Codex, --dangerously-skip-permissions for Agy, --allow-all for Copilot, --approval-mode yolo for Qwen, --auto for OpenCode).

For sensitive repositories, production checkouts, or when confirmation dialogs are preferred:

• Pass --safe to quintet team:

  $BIN team 1:claude:implementer,1:codex:test-engineer "refactor auth" --safe

• Or set export QUINTET_SAFE_MODE=true.

In safe mode, workers block on approval prompts (tool approval, trust-folder). Run quintet team doctor <name> to find stalled workers, then answer with team send:

$BIN team doctor export-feat
$BIN team send export-feat w1-codex "y" --force

(team send refuses while a recognized dialog is showing, since its Enter answers it; --force is how you answer on purpose.)

First run in a new folder (trust dialog)

Claude asks "Is this a project you created or one you trust?" the first time it opens a folder, and Enter there selects "No, exit". The kickoff therefore checks each pane before typing: with any recognized dialog up, the task is held (teams/<name>/held/<worker>.txt, a [quintet] <worker> HELD: <modal> taskboard line, and a WARN). Answer it in tmux attach -t quintet-<name>, then $BIN team resume <name> [worker] (no worker = all held). quintet never answers the trust dialog itself, since Claude can record the trust on a parent folder. There is no escalation path yet: nothing pauses a worker and asks the orchestrator, so someone has to poll doctor. Doctor exits nonzero when a pane can't be captured (inspection error) or when team.json and the live windows disagree (missing or extra worker). "No recognized modal" means only that none of the known prompt patterns matched.

Team windows stay open as dead panes after a worker's CLI exits (remain-on-exit), so output can be read with team capture; team shutdown removes them.

State Retention & Garbage Collection (quintet prune)

To clean up defunct team state directories and expired debate transcripts:

$BIN prune [--days N] [--dry-run]

• Scans QUINTET_STATE_DIR/teams/ for directories whose tmux session has terminated. Active teams are never removed. Each team is checked and deleted under a per-team lock that team start also takes.
• Scans QUINTET_HOME/debates/ for debate transcripts older than N days (default: 7).
• Age means inactivity: the newest mtime of the directory and the files in it. A directory whose timestamp can't be read is skipped with a WARN.
• Kills orphaned quintet-fleet-<epoch>-* sessions older than 60 minutes (e.g. from an interrupted fleet run).
• Pass --days 0 to immediately prune all dead sessions and aged debate transcripts. --dry-run lists candidates and deletes nothing. --force is a deprecated no-op.
• Fails closed: if tmux is missing, or tmux list-sessions fails for any reason other than "no server running" (no socket, or a stale socket left by a crashed server), prune exits nonzero and deletes nothing.
• State dirs whose name isn't a valid team name (^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$) and anything under QUINTET_HOME/teams/ are skipped with a WARN; prune prints the rm -rf command to remove an invalid-named dir by hand.
• Exits nonzero if any removal failed.

The team manifest

team.json is the source of truth for a running team — read it to recover state after a disconnect or to script monitoring:

{
  "name": "export-feat",
  "cwd": "/path/to/repo",
  "session": "quintet-export-feat",
  "no_mcp": false,
  "safe_mode": false,
  "started": "2026-05-25T04:30:00Z",
  "goal": "build the export feature",
  "workers": [
    { "name": "w1-codex-implementer",  "provider": "codex", "role": "implementer",   "model": "gpt-6.1-sol" },
    { "name": "w2-codex-test-engineer", "provider": "codex", "role": "test-engineer", "model": "default" },
    { "name": "w3-agy-code-reviewer",  "provider": "agy",   "role": "code-reviewer", "model": "gemini-3.1-pro-high" },
    { "name": "w4-qwen",               "provider": "qwen",  "role": "stock",         "model": "default" }
  ]
}

Each worker object records {"name", "provider", "role", "model", "effort", "no_mcp_effective"}; the per-worker subtask is recorded in the taskboard (taskboard.md), not the manifest. The session field is the tmux session to attach to (tmux attach -t <session>).

If a session is orphaned (you lost the terminal), team list plus this file is enough to re-attach, capture, or shut it down cleanly.

Reading the taskboard

Each worker appends status lines to taskboard.md and ends with a DONE line. Poll it alongside team capture:

[w1-codex] serializer implemented in src/export/csv.rs
[w3-agy] alt approach: stream rows to avoid buffering 10M rows
[w4-qwen] docs/export.md drafted
[w1-codex] DONE

Treat these as self-reported, not ground truth — read the real files and run the tests yourself before trusting a DONE. A copy-paste-ready taskboard skeleton lives in assets/taskboard-template.md.

Provider selection

Match each subtask to the provider best suited to it. Quick rule: Codex/Claude for implementation, Agy/Gemini for breadth and research, Copilot for an extra perspective, Qwen for free-tier bulk volume. The canonical, maintained mapping is in references/provider-strengths.md.

A full worked example

The user wants a CSV export feature built in parallel. Walk the whole lifecycle:

1. Decompose by ownership. Four non-overlapping concerns: the serializer (src/export/), its tests (tests/export/), docs (docs/), and an edge-case audit (read-only, writes only to the taskboard). No two workers touch the same files — that is the rule that prevents corruption.

2. Map providers to work. Serializer → codex (strong implementer). Tests → a second codex worker. Docs → agy (good prose/breadth). Audit → qwen (free-tier, fine for a read-and-report pass).

3. Launch with the team command above, then immediately team capture export-feat to confirm every REPL came up and accepted its task (not a bare shell prompt).

4. Monitor in a poll loop. Every ~30s: team status, skim team capture, read taskboard.md. When w3-agy drifts into the legacy path, steer it: team send export-feat w3-agy "skip legacy; v2 API only".

5. Verify, don't trust. When the taskboard shows DONE, open src/export/csv.rs, run cargo test export, and confirm the docs exist. Only then team shutdown export-feat.

The discipline that makes this work: scope by files, verify by artifacts. Everything else is mechanics.

Critical rules

• File ownership: never give two workers overlapping files. This is the #1 cause of corruption. Scope subtasks by directory/module.
• Verify launch: after starting, run team capture to confirm each agent REPL came up and accepted the task. Cold-start warmup is provider-specific (tune via QUINTET_<PROVIDER>_WARMUP seconds).
• Autonomy flags: defaults launch agents in fully unattended modes so they can write to the worktree without stopping for approvals — claude --permission-mode bypassPermissions, codex --yolo, copilot --allow-all-tools, agy --dangerously-skip-permissions, qwen --approval-mode yolo with GEMINI_CLI_TRUST_WORKSPACE/QWEN_CLI_TRUST_WORKSPACE=true (qwen lacks --skip-trust, so the trust env is what actually unblocks its file writes), and opencode --auto. Anything less (e.g. acceptEdits) deadlocks workers on trust/permission gates with no human to dismiss them. Override per provider via QUINTET_<PROVIDER>_LAUNCH for stricter sandboxing — but only when a human is watching the panes.
• Verify artifacts, not the taskboard: the taskboard is self-reported; the files and tests are the proof.
• No providers ready: if doctor reports an empty pool, the launch fails — authenticate at least one CLI first (see skills/quintet-orchestration).

Troubleshooting

FAQ

Can I add a worker to a running team? No — teams are fixed at launch. Shut down and relaunch with the new spec, or run a second small team for the extra work.

Do workers see each other's output? Not directly. They share a cwd and the taskboard; coordinate explicit dependencies by ordering subtasks or steering with team send.

What happens to a worker that finishes early? It idles in its REPL until shutdown. That's fine — it costs nothing but a tmux window.

How do I keep the state after a run? team shutdown <name> (without --force) preserves team.json and taskboard.md under QUINTET_STATE_DIR for later inspection.

Is tmux really required? Yes, for team mode — workers are persistent interactive sessions. If you can't install tmux, use fleet mode (skills/quintet-fleet-dispatch), which is headless.

Scaling and worker count

More workers is not more throughput past a point — overlap and review overhead grow faster than parallelism helps.

• 1–2 workers: a focused change with a clean split (impl + tests). Easiest to verify.
• 3–5 workers: the sweet spot for a feature with naturally separate concerns (impl, tests, docs, audit). Most real teams live here.
• 6–10 workers: only when the repo genuinely has that many non-overlapping modules. Past this you spend more time decomposing and verifying than you save.
• Hard cap: 10. The launcher refuses more; if you think you need them, your subtasks probably overlap and should be merged.

The bottleneck is almost never compute — it's decomposition quality. Three well-scoped workers that never touch the same file beat eight that fight over one.

Sandboxing and autonomy

Workers launch in fully unattended modes by default so they can work without stopping for approvals — claude --permission-mode bypassPermissions, codex --yolo, copilot --allow-all-tools, agy --dangerously-skip-permissions, qwen --approval-mode yolo (prefixed with GEMINI_CLI_TRUST_WORKSPACE=true QWEN_CLI_TRUST_WORKSPACE=true, since the qwen fork has no --skip-trust flag and would otherwise refuse to write in an untrusted directory), and opencode --auto. This is required, not merely convenient: a team worker has no human at its pane, so any mode that pauses on a trust or permission gate (e.g. claude --permission-mode acceptEdits) silently deadlocks the whole run. That is the right default for a scratch repo or a worktree, and the wrong one for a production checkout.

The one-shot fleet/debate path is deliberately the opposite: it runs each provider headless and read-only behind the advisory preamble (no file writes expected), so sandbox-default invocations there are fine — the unattended write-access flags above apply only to team workers that are actually doing work.

Tighten it per provider with QUINTET_<P>_LAUNCH, which overrides the entire launch command for that provider's workers:

# Run claude workers in a stricter mode for this team
export QUINTET_CLAUDE_LAUNCH='claude --permission-mode default'
$BIN team 2:claude "refactor auth" --name auth --cwd ./repo --tasks "...||..."

Safer still on an important repo: point --cwd at a git worktree or a branch checkout, so autonomous edits are isolated and trivially discarded if a worker goes wrong. Confirm scope with the user before launching write-capable workers on anything you can't cheaply revert.

Recovering an orphaned team

If you lose the terminal or a session compacts mid-run, the team keeps running detached. Recover it:

$BIN team list                           # find the session by name
$BIN team status <name>                  # confirm it's still alive
tmux attach -t quintet-<name>            # watch live (Ctrl-b d to detach)
$BIN team capture <name>                 # or pull worker output headless

team.json + taskboard.md under QUINTET_STATE_DIR hold everything you need to decide whether to keep steering it or shutdown --force. Nothing is lost just because the controlling terminal went away.

Key environment variables

Tune team behavior without editing the CLI:

<P> is the uppercase provider name (CLAUDE, CODEX, AGY, COPILOT, QWEN, OPENCODE). Raise warmup when a worker's window shows a shell prompt instead of the agent at launch.

Related skills

See also:

• skills/quintet-orchestration — the router that decides team vs fleet and handles readiness checks.
• skills/quintet-fleet-dispatch — the one-shot, read-only counterpart for questions and reviews.
• skills/quintet-discipline — a worker's DONE is self-reported, not proof; verify artifacts before claiming the team succeeded.

When to load the references

Load on demand at the decision point — not up front:

• Before composing the --tasks split, read references/provider-strengths.md for the canonical provider→subtask mapping (which model owns implementation vs research vs bulk).
• When seeding taskboard.md for a new team, copy the skeleton from assets/taskboard-template.md.
• When recovering an orphaned team or diagnosing a worker that won't launch, read references/operations.md for worker naming, the coordination model, and the full failure table.
• Do NOT load these while merely monitoring a healthy running team — team status / team capture and the body above cover the steady state.