# 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

```markdown
### 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 Multi-Agent Orchestration

> **Important:** ClawTeam CLI command is `oh`. On our OpenClaw setup, ALWAYS explicitly specify `tmux openclaw` as backend+agent — `oh spawn` defaults to `claude` which we don't have.
> Official repo: https://github.com/HKUDS/ClawTeam

### ⚠️ CRITICAL: Spawn Syntax

```
oh spawn tmux openclaw --team <team> --agent-name <name> --task "<task>"
```

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

### Team Setup

```bash
# 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"

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

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

### Task Management

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

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

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

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

### Spawn Workers (OpenClaw Specific)

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

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

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

### Communication (Inbox)

```bash
# Send message to agent
oh inbox send <team> <to-agent> "<message>"

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

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

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

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

### Profiles & Presets

```bash
# List built-in provider templates
oh preset list
oh preset show <provider-name>

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

# Or use interactive TUI
oh profile wizard

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

# Fix broken profile on fresh machine
oh profile doctor claude
```

### Git Context & Conflict Checks

```bash
oh context log <team>
oh context diff <team>
oh context files <team>
oh context conflicts <team>
oh context inject <team> --agent <name>
```

### Workspace Management

```bash
oh workspace list <team>
oh workspace merge <team> <agent-name>
```

### Snapshots & Recovery

```bash
oh team snapshot <team> --tag <tag-name>
oh team snapshots <team>
oh team restore <team> --snapshot <tag-name>
```

### Worker Loop Protocol

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

```bash
# 1. Check tasks
oh task list <team> --owner <me>

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

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

### Cleanup

```bash
oh team cleanup <team>          # kill workers, cleanup worktrees
oh lifecycle request-shutdown <team>
```

### JSON Output

```bash
oh --json team discover
oh --json board show <team>
oh --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/`