open-claw-team/.openclaw/workspace/TOOLS.md

TOOLS.md - Local Notes

Skills define how tools work. This file is for your specifics — the stuff that's unique to your setup.

What Goes Here

Things like:

• Camera names and locations
• SSH hosts and aliases
• Preferred voices for TTS
• Speaker/room names
• Device nicknames
• Anything environment-specific

Examples

### Cameras

- living-room → Main area, 180° wide angle
- front-door → Entrance, motion-triggered

### SSH

- home-server → 192.168.1.100, user: admin

### TTS

- Preferred voice. Preferred: "Nova" (warm, slightly British)

ClawTeam Templates

Available templates in ~/.clawteam/templates/:

dev-team.toml

• leader — Tech Lead / Orchestrator
• fullstack-dev — Versatile backend+frontend developer
• frontend-dev — UI components, state, responsive, accessibility
• backend-dev — APIs, databases, auth, security
• uxui-dev — Design system, visual polish, micro-interactions
• qc-lead — Quality gate manager, coordinates reviews
• code-reviewer — Architecture, logic, TDD, security review
• qa-engineer — Test coverage, edge cases, regression tests
• devops-engineer — CI/CD, Docker, deployment, monitoring

qc-team.toml

• qc-lead — QC Lead, quality gate
• code-reviewer — Code quality review
• test-engineer — Test validation
• acceptance-auditor — Final acceptance audit

Template Usage

# Use template when spawning team (clawteam handles template loading)
clawteam team spawn-team <team-name> -d "<description>" -n leader
# Then create tasks matching template.tasks
clawteam task create <team> "<task>" -o <owner>
# Spawn workers matching template.agents
# ❌ WRONG: NEVER use subprocess — agents die immediately after shell exits
# clawteam spawn subprocess openclaw --team <team> --agent-name <name> --task "..."

# ✅ CORRECT: always use tmux openclaw for persistent agent sessions
clawteam spawn tmux openclaw --team <team> --agent-name <name> --task "..."

ClawTeam Multi-Agent Orchestration

Important: ClawTeam CLI command is clawteam. ALWAYS specify tmux openclaw as the backend — NEVER use subprocess. Default claude is not available. Official repo: https://github.com/HKUDS/ClawTeam

⚠️ CRITICAL: Spawn Syntax

clawteam spawn tmux openclaw --team <team> --agent-name <name> --task "<task>"

NOT clawteam spawn --team ... (defaults to claude → will fail) NOT clawteam spawn tmux claude (we don't have claude CLI)

Team Setup

# Create team (you become the leader — set env vars first)
export CLAWTEAM_AGENT_ID="leader-001"
export CLAWTEAM_AGENT_NAME="leader"
export CLAWTEAM_AGENT_TYPE="leader"

clawteam team spawn-team <team-name> -d "<description>" -n leader

# View team status
clawteam status
clawteam board show <team-name>
clawteam board attach <team-name>          # tiled tmux view

Task Management

# Create tasks (with owner, dependencies, priority)
clawteam task create <team> "<task description>" -o <owner>
clawteam task create <team> "<task>" -o <owner> --blocked-by <task-id>
clawteam task create <team> "Hotfix" -o <owner> --priority high

# Update status
clawteam task update <team> <task-id> --status pending
clawteam task update <team> <task-id> --status in_progress
clawteam task update <team> <task-id> --status completed
clawteam task update <team> <task-id> --status blocked

# List/filter tasks
clawteam task list <team> --status pending
clawteam task list <team> --owner <agent-name>
clawteam task list <team> --priority high

# Wait for all sub-agents to finish
clawteam task wait <team>
clawteam task wait <team> --timeout 300 --poll-interval 10

Spawn Workers (OpenClaw Specific)

# ✅ CORRECT — always use tmux openclaw
clawteam spawn tmux openclaw --team <team> --agent-name <name> --task "<task>"

# ✅ With non-default provider/model via profile
clawteam spawn tmux --profile <profile-name> --team <team> --agent-name <name> --task "<task>"

# ❌ WRONG — defaults to claude
clawteam spawn --team <team> --agent-name <name> --task "<task>"
clawteam spawn tmux claude --team <team> --agent-name <name> --task "<task>"

Communication (Inbox)

# Send message to agent
clawteam inbox send <team> <to-agent> "<message>"

# Broadcast to all
clawteam inbox broadcast <team> "<message>"

# Receive (destructive — consumes message)
clawteam inbox receive <team> --agent <name>

# Peek (non-destructive)
clawteam inbox peek <team> --agent <name>

# Watch for new messages
clawteam inbox watch <team> --agent <name>

Profiles & Presets

# List built-in provider templates
clawteam preset list
clawteam preset show <provider-name>

# Generate reusable profile from preset
clawteam preset generate-profile <preset> <base-agent> --name <profile-name>

# Or use interactive TUI
clawteam profile wizard

# Test a profile before using in team
clawteam profile test <profile-name>

# Fix broken profile on fresh machine
clawteam profile doctor claude

Git Context & Conflict Checks

clawteam context log <team>
clawteam context diff <team>
clawteam context files <team>
clawteam context conflicts <team>
clawteam context inject <team> --agent <name>

Workspace Management

clawteam workspace list <team>
clawteam workspace merge <team> <agent-name>

Snapshots & Recovery

clawteam team snapshot <team> --tag <tag-name>
clawteam team snapshots <team>
clawteam team restore <team> --snapshot <tag-name>

Worker Loop Protocol

Workers should NOT exit after completing their initial task. Expected loop:

# 1. Check tasks
clawteam task list <team> --owner <me>

# 2. Check inbox for new instructions
clawteam inbox receive <team> --agent <me>

# 3. If idle, notify leader
clawteam lifecycle idle <team>

Cleanup

clawteam team cleanup <team>          # kill workers, cleanup worktrees
clawteam lifecycle request-shutdown <team>

JSON Output

clawteam --json team discover
clawteam --json board show <team>
clawteam --json task list <team> --status pending

Requires:

• pip install clawteam
• Python 3.10+
• tmux installed
• OpenClaw CLI available on PATH (openclaw)
• Git repo for worktree isolation
• Data directory: ~/.clawteam/

✅ Confirmed Working Commands

# Create team
clawteam team spawn-team <team> -d "<description>" -n <leader>

# Create task (gets task ID back)
clawteam task create <team> "<task>" -o <owner>
# Output: OK Task created: <TASK_ID>

# Spawn worker with task description
clawteam spawn tmux openclaw --team <team> --agent-name <name> --agent-type coder \
  --task "Do X. After done: clawteam task update <team> <TASK_ID> --status completed"

# ❌ WRONG — subprocess agents die immediately; never use this
# clawteam spawn subprocess openclaw --team <team> --agent-name <name> --task "..."

# ✅ ALWAYS use tmux (persistent, monitorable, survives network blips)
# clawteam spawn tmux openclaw --team <team> --agent-name <name> --task "..."

# View board
clawteam board show <team>

# Mark task done
clawteam task update <team> <task-id> --status completed

### ⚠️ Flags That DON'T Exist on clawteam spawn
- `--model` (model is set by OpenClaw config, not clawteam)
- `--timeout` (no timeout flag on spawn)
- `-m` (conflicts with clawteam's own options)

### 📌 Critical Reminders
- **ALWAYS use `tmux openclaw`** — `subprocess` agents die immediately
- **Set task dependencies**: `clawteam task update <team> <id> --add-blocked-by <dep-id>`
- **Verify agents alive**: `tmux list-sessions | grep clawteam`
- **Monitor progress**: `clawteam board attach <team>`
- **Check in-progress tasks**: `clawteam task list <team> --status in_progress`
- **Unblock stuck tasks**: use `clawteam task update <team> <id> --status pending` after resolving blocker