Clawteam

clawteam — ClawTeam runtime operator router

Use this skill when the real question is "which ClawTeam operator packet do I need right now?"

clawteam owns the ClawTeam-specific runtime surface:

• team / task / inbox state
• worker spawning through tmux or subprocess
• workspace or git-worktree isolation
• board visibility and recovery flows
• template launches
• provider / preset / profile setup tied to spawn behavior

It does not own generic multi-agent orchestration, board governance, or lightweight subtask fan-out.

Read these support docs before stretching the boundary:

• references/intake-packets-and-route-outs.md
• references/operator-modes-and-route-outs.md
• references/architecture.md
• references/agent-types.md
• references/use-cases.md

When to use this skill

• The user explicitly says clawteam or clearly wants ClawTeam's team/task/inbox/worktree runtime
• A leader should coordinate named workers with explicit task ownership and message passing
• The user wants ClawTeam board commands such as board attach, board live, or board serve
• The user wants a built-in ClawTeam template launch
• The real blocker is provider/model/profile setup inside ClawTeam before spawn
• The workflow spans developer delivery, product/ops research, content operations, or game work and the chosen runtime is ClawTeam

When not to use this skill

• Generic multi-agent implementation loop with planning + QA → jeo, omc, omx, or ohmg
• Board/work queue control outside the ClawTeam runtime → vibe-kanban
• Lightweight parallel subtasks with no team/task/inbox/worktree state → built-in delegation / subagents
• Planning or decomposition → task-planning
• Tool comparison or platform survey → survey

Instructions

Step 1: Start from the packet already in hand

Use references/intake-packets-and-route-outs.md.

Normalize the request into one packet first:

clawteam_packet:
  primary_packet: manual-team | template-launch | monitor-recover | profile-setup | route-out
  backend: tmux | subprocess | unknown
  audience: developer-workflow | product-ops | marketing-content | game-production | mixed
  current_pain: ownership-split | quick-start | stuck-runtime | provider-setup | wrong-tool
  confidence: high | medium | low

Choose one primary packet only:

• manual-team — explicit team lifecycle, worker roles, tasks, inboxes, dependencies
• template-launch — launch a prebuilt ClawTeam team and monitor it
• monitor-recover — inspect a running/stuck team, board, inbox, tasks, workspaces, or lifecycle state
• profile-setup — preset/profile/provider/model/runtime setup before spawn
• route-out — the request is not really about ClawTeam's runtime

Rule: if the user really means “multiple agents” rather than “ClawTeam,” route out immediately.

Step 2: Verify the minimal runtime before giving deeper commands

Check what already works before assuming ClawTeam will smooth it over.

python3 --version
clawteam --help

tmux -V

# Replace with the agent CLI the user actually wants to run:
claude --version
codex --version

Rules: 1. If the underlying agent CLI does not work by itself, do not pretend clawteam spawn will fix it. 2. Prefer tmux for visible interactive workers and live operator control. 3. Prefer subprocess only when headless/background execution is the real need. 4. If provider/model customization is the blocker, choose profile-setup before large spawn examples.

Step 3: Return the smallest useful command packet

Packet A — manual-team

Use this when ownership and dependencies must stay explicit.

clawteam team spawn-team my-team -d "Build the auth module" -n leader
clawteam spawn tmux claude --team my-team --agent-name architect --task "Design the API schema"
clawteam spawn tmux codex --team my-team --agent-name tester --task "Write integration tests"
clawteam task create my-team "Design the API schema" -o architect
clawteam inbox send my-team tester "Wait for API handoff before final checks"
clawteam board attach my-team

Use references/use-cases.md if the user needs fuller examples for fullstack, research, content, or game-production splits.

Packet B — template-launch

Use this when a built-in template already matches the job.

clawteam template list
clawteam launch hedge-fund --team fund1 --goal "Analyze AAPL, MSFT, NVDA for Q2 2026"
clawteam board attach fund1

Do not bury this in a full manual-team walkthrough unless the template clearly fails to fit.

Packet C — monitor-recover

Use this when a team already exists or runtime truth is the real question.

clawteam team discover
clawteam team status my-team
clawteam board show my-team
clawteam task list my-team --status blocked
clawteam inbox peek my-team
clawteam workspace list my-team

Use this packet to inspect stuck workers, blocked tasks, missing inbox activity, or workspace drift.

Packet D — profile-setup

Use this when the runtime/provider setup is the actual blocker.

clawteam preset list
clawteam preset show moonshot-cn
clawteam preset generate-profile moonshot-cn claude --name claude-kimi
clawteam profile doctor claude
MOONSHOT_API_KEY=*** clawteam profile test claude-kimi
clawteam spawn tmux --profile claude-kimi --team my-team --agent-name researcher --task "Compare onboarding flows"

Use this packet before large team examples when the question is really about provider/model/runtime configuration.

Step 4: Keep the runtime reality honest

ClawTeam-style workflows are still operator-heavy.

State these realities when relevant:

• tmux + worktree/session inspection is often part of the real workflow, not an implementation detail
• long-running worker persistence may be fragile in some flows; do not oversell it
• trust prompts, permission flows, and backend-specific quirks can still leak through the abstraction
• manual cleanup, merge, or workspace hygiene may still matter after a run

Important upstream caveats:

• issue #148 documents worker keepalive problems in ongoing-job subprocess patterns
• issue #146 documents gaps between parsed agent definitions/configs and applied runtime behavior

If the user wants generic orchestration policy, board governance, or lightweight built-in delegation, route outward instead of growing this skill.

Step 5: Return one concise operator brief

Preferred format:

# ClawTeam Operator Brief

## Packet
- Packet:
- Why it fits:
- Backend:

## Preconditions
- Verified:
- Missing / risky:

## Commands
1. ...
2. ...
3. ...

## Monitoring / recovery
- ...

## Caveats
- ...

## Route-outs kept out of scope
- ...

Short, truthful packets beat giant command dumps.

Examples

Example 1: Fullstack feature split

Input

Use ClawTeam to split a full-stack feature across a leader and two workers.

Good output direction

• choose manual-team
• verify the runtime and worker CLI first
• create the team, spawn workers, create explicit tasks, and end with a board command
• keep planning/review policy outside this skill

Example 2: Template first

Input

Launch a built-in ClawTeam team and let me watch it.

Good output direction

• choose template-launch
• use template list if needed
• use launch ... --team ... --goal ...
• monitor with board attach or board serve

Example 3: Runtime recovery

Input

A ClawTeam worker keeps dying after its first turn. What should I check?

Good output direction

• choose monitor-recover
• inspect team, board, task, inbox, and workspace state
• mention that long-running worker persistence is not guaranteed in every flow
• avoid pretending a generic orchestration skill owns the problem

Example 4: Honest route-out

Input

I just need a generic multi-agent implementation loop with planning and QA.

Good output direction

• choose route-out
• recommend jeo, omc, omx, or ohmg
• explain that clawteam is the ClawTeam runtime/operator surface, not the generic answer to every multi-agent request

Best practices

1. Pick one packet first instead of dumping every ClawTeam command family. 2. Verify the underlying agent CLI and backend before spawning workers. 3. Prefer tmux for visible operator control; use subprocess only when headless execution is the real need. 4. Use template launch only when the built-in archetype actually fits. 5. Treat provider/profile setup as its own path. 6. Keep worker persistence and config-application caveats explicit. 7. Keep clawteam distinct from orchestration routers, planning skills, and board-governance tools. 8. Update compact and discovery surfaces when the trigger wording changes materially.

References

• ClawTeam README
• PyPI: clawteam
• references/intake-packets-and-route-outs.md
• references/operator-modes-and-route-outs.md
• references/architecture.md
• references/agent-types.md
• references/use-cases.md

Agent types and spawn paths

ClawTeam works with CLI agents that already run correctly on their own.

Rule zero

Verify the raw agent command first.

claude --version
codex --version
cursor --help

If the agent command does not work outside ClawTeam, fix that first.

Common spawn patterns

Role naming guidance

Use semantic names:

• architect
• backend
• tester
• researcher
• content-editor
• build-reviewer

Avoid generic names like worker-1 unless the user truly does not care about ownership clarity.

Prompt / coordination expectations

Spawned workers are expected to:

• inspect their tasks
• update task status
• read and send inbox messages
• report idle or completion state

Representative operator commands:

clawteam task list my-team --owner backend
clawteam task update my-team 2 --status in_progress
clawteam task update my-team 2 --status completed
clawteam inbox send my-team leader "Auth flow is ready for review"
clawteam inbox receive my-team
clawteam lifecycle idle my-team

Provider-aware setup

When the blocker is provider/model/runtime configuration, use profiles and presets instead of improvising every spawn command:

clawteam preset list
clawteam preset generate-profile moonshot-cn claude --name claude-kimi
clawteam profile doctor claude
clawteam profile test claude-kimi

Caveats

• tmux is the default happy path for visible teams.
• subprocess is useful but deserves more caution for long-running workers.
• Do not assume advanced agent-definition files are fully honored without testing.

ClawTeam architecture

Overview

ClawTeam is a filesystem-first swarm runner. It combines:

• team state (team, task, inbox, workspace, lifecycle commands)
• worker runtime backends (tmux or subprocess)
• workspace isolation (typically git worktrees)
• monitoring surfaces (board show/live/attach/serve)
• provider/runtime profiles (preset, profile)

Core operator surfaces

Team lifecycle

clawteam team spawn-team my-team -d "Build the auth module" -n leader
clawteam team discover
clawteam team status my-team
clawteam team cleanup my-team --force

Worker spawning

# tmux backend
clawteam spawn tmux claude --team my-team --agent-name architect --task "Design the API schema"
clawteam spawn tmux codex  --team my-team --agent-name tester   --task "Write integration tests"

# subprocess backend
clawteam spawn subprocess cursor --team my-team --agent-name reviewer --task "Review the landing page copy"

Task and inbox state

clawteam task create my-team "Implement auth flow" -o backend
clawteam task update my-team 2 --status in_progress
clawteam task update my-team 2 --status completed
clawteam task list my-team --status blocked

clawteam inbox send my-team backend "Wait for API spec handoff"
clawteam inbox receive my-team
clawteam inbox peek my-team

Monitoring

clawteam board show my-team
clawteam board live my-team --interval 3
clawteam board attach my-team
clawteam board serve --port 8080

Workspace isolation

Typical runs give each worker its own git worktree / isolated workspace so parallel workers can operate without stomping on each other.

Useful commands:

clawteam workspace list my-team
clawteam workspace checkpoint my-team backend
clawteam workspace merge my-team backend
clawteam workspace cleanup my-team backend

Runtime settings

Provider/model/runtime settings increasingly flow through presets and profiles rather than ad hoc environment juggling.

clawteam preset list
clawteam preset show moonshot-cn
clawteam preset generate-profile moonshot-cn claude --name claude-kimi
clawteam profile doctor claude
clawteam profile test claude-kimi

Operational caveats

• Long-running worker persistence is not guaranteed in all backends. Upstream issue #148 documents keepalive problems for ongoing-job subprocess patterns.
• Parsed agent-definition/config files may not fully apply at runtime. Upstream issue #146 documents gaps between parsed definitions and actual spawn behavior.
• ClawTeam is strongest when the user truly wants explicit team/task/inbox/worktree state; generic orchestration requests may belong elsewhere.

ClawTeam intake packets and route-outs

Start from one packet

Fast route-outs

• Generic multi-agent planning + implementation + QA → jeo, omc, omx, ohmg
• Board/work queue governance outside ClawTeam runtime control → vibe-kanban
• Planning / decomposition → task-planning
• Tool comparison or landscape research → survey
• Lightweight parallel fan-out without team/task/inbox/worktree state → built-in delegation / subagents

Backend reality

Reality checks to say out loud

• ClawTeam workflows still often involve tmux/worktree inspection and manual operator oversight.
• Worker persistence is not guaranteed in every backend or prompt shape.
• Provider/profile/config abstractions should be verified, not assumed.
• Cleanup, merge, and workspace hygiene may still be manual after the run.

ClawTeam operator modes and route-outs

Start with intake-packets-and-route-outs.md when you need the fastest packet choice. Use this document when the packet is already known and you want the more detailed mode table.

Choose one mode first

Route-outs

Use another skill when the job is mainly:

• integrated planning → execution → QA orchestration: jeo, omc, omx, ohmg
• planning and decomposition: task-planning
• board/work queue control outside ClawTeam: vibe-kanban
• cross-platform landscape research or tool comparison: survey
• lightweight parallel subtasks without team/task/inbox/worktree state: built-in delegation/subagents

Backend choice

Reality notes

• Upstream issue #148 documents worker keepalive problems for ongoing-job subprocess flows. Do not present long-running workers as guaranteed.
• Upstream issue #146 documents agent-definition/config application gaps. Verify behavior instead of assuming all parsed config fields are honored.
• If the user wants ClawTeam because of the explicit team/task/inbox/worktree contract, stay in this skill. If they only want "multiple agents," route outward.

ClawTeam use cases

1. Fullstack feature split

Use manual-team when roles and dependencies matter.

clawteam team spawn-team shop -d "Ship invite flow" -n leader
clawteam spawn tmux claude --team shop --agent-name architect --task "Design invite API and schema"
clawteam spawn tmux claude --team shop --agent-name backend   --task "Implement invite endpoints"
clawteam spawn tmux codex  --team shop --agent-name tester    --task "Write integration tests"

clawteam task create shop "Design invite API and schema" -o architect
clawteam task create shop "Implement invite endpoints" -o backend
clawteam task create shop "Write integration tests" -o tester --blocked-by 2

clawteam board attach shop

2. Product / ops research swarm

Use manual-team when the team needs explicit parallel ownership with synthesis.

clawteam team spawn-team launch-research -d "Analyze onboarding friction and activation risks" -n leader
clawteam spawn tmux claude --team launch-research --agent-name user-research   --task "Summarize interview patterns"
clawteam spawn tmux claude --team launch-research --agent-name analytics       --task "Inspect funnel drop-offs"
clawteam spawn tmux codex  --team launch-research --agent-name synthesis       --task "Merge findings into one operator memo"

clawteam task create launch-research "Summarize interview patterns" -o user-research
clawteam task create launch-research "Inspect funnel drop-offs" -o analytics
clawteam task create launch-research "Merge findings into one memo" -o synthesis --blocked-by 1,2

3. Marketing / content studio

Use manual-team when content creation and QA can run in parallel but still need explicit review handoffs.

clawteam team spawn-team campaign -d "Ship launch-week content pack" -n lead
clawteam spawn tmux claude --team campaign --agent-name landing-page  --task "Draft landing page updates"
clawteam spawn tmux claude --team campaign --agent-name email-sequence --task "Draft launch emails"
clawteam spawn tmux codex  --team campaign --agent-name qa           --task "Check links, UTMs, and publishing checklist"

clawteam board serve --port 8080

4. Game / simulation milestone swarm

Use manual-team when code, content, QA, and distribution roles all matter.

clawteam team spawn-team demo-milestone -d "Prepare streamer-ready demo build" -n lead
clawteam spawn tmux claude --team demo-milestone --agent-name gameplay  --task "Polish tutorial and controller support"
clawteam spawn tmux claude --team demo-milestone --agent-name build      --task "Prepare and package the demo build"
clawteam spawn tmux codex  --team demo-milestone --agent-name qa         --task "Run smoke checks and capture release blockers"

5. One-command template launch

Use launch-template when the built-in archetype already fits.

clawteam template list
clawteam launch hedge-fund --team fund1 --goal "Analyze AAPL, MSFT, NVDA for Q2 2026"
clawteam board attach fund1

6. Provider-aware runtime setup

Use profile-setup when the runtime configuration is the actual blocker.

clawteam preset list
clawteam preset show moonshot-cn
clawteam preset generate-profile moonshot-cn claude --name claude-kimi
clawteam profile doctor claude
MOONSHOT_API_KEY=*** clawteam profile test claude-kimi

Notes

• Prefer template launch when the archetype is already known.
• Prefer manual teams when dependencies, ownership, or mixed agents need to be explicit.
• Use monitoring commands (board show/live/attach/serve) as the verification path, not just raw spawn output.