Terminals - Worker Spawning

Spawn and manage Claude workers via TabzChrome API.

MCP Tools (Preferred)

# Spawn worker with profile
tabz_spawn_profile(
    profileId="claude-worker",
    workingDir="~/projects/.worktrees/ISSUE-ID",
    name="ISSUE-ID"
)

REST API

Spawn Terminal

TOKEN=$(cat /tmp/tabz-auth-token)
PROJECT_DIR="/home/user/projects/myapp"  # Main repo path
curl -X POST http://localhost:8129/api/spawn \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $TOKEN" \
  -d "{
    \"name\": \"ISSUE-ID\",
    \"workingDir\": \"$PROJECT_DIR/.worktrees/ISSUE-ID\",
    \"command\": \"BEADS_WORKING_DIR=$PROJECT_DIR claude\"
  }"

Find Worker

# By name
curl -s http://localhost:8129/api/agents | jq -r '.data[] | select(.name == "ISSUE-ID")'

# Get session ID
SESSION=$(curl -s http://localhost:8129/api/agents | jq -r '.data[] | select(.name == "ISSUE-ID") | .id')

Kill Worker

curl -s -X DELETE "http://localhost:8129/api/agents/$SESSION" \
  -H "X-Auth-Token: $TOKEN"

Git Worktrees

Worktrees enable parallel workers on same repo.

# REQUIRED for beads projects - creates .beads/redirect for MCP tools
bd worktree create .worktrees/ISSUE-ID --branch feature/ISSUE-ID

# Remove
git worktree remove ".worktrees/ISSUE-ID" --force
git branch -d "feature/ISSUE-ID"

Critical: Always use bd worktree create for beads projects. It creates .beads/redirect which points MCP tools to the main database. Without this file, MCP tools fail silently and workers must use CLI only.

Fallback (non-beads projects only):

git worktree add ".worktrees/ISSUE-ID" -b "feature/ISSUE-ID"

Dependency Initialization

Worktrees share git but NOT node_modules. Initialize before spawning:

INIT_SCRIPT=$(find ~/plugins ~/.claude/plugins -name "init-worktree.sh" -path "*spawner*" 2>/dev/null | head -1)
$INIT_SCRIPT ".worktrees/ISSUE-ID"

Sending Prompts

Wait for Claude to boot (8+ seconds), then:

# Find safe-send-keys.sh
SAFE_SEND_KEYS=$(find ~/plugins ~/.claude/plugins -name "safe-send-keys.sh" -path "*spawner*" 2>/dev/null | head -1)

# Send prompt
"$SAFE_SEND_KEYS" "$SESSION" "Complete beads issue $ISSUE_ID. Run: bd show $ISSUE_ID --json"

Fallback:

tmux send-keys -t "$SESSION" -l "$PROMPT"
sleep 1
tmux send-keys -t "$SESSION" C-m

Worker Naming

Use issue ID as terminal name: - Easy lookup via /api/agents - Clear dashboard display - Correlation: terminal = issue = branch = worktree

Critical Settings

Dashboard

Monitor workers with tmuxplexer:

curl -s -X POST http://localhost:8129/api/spawn \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $TOKEN" \
  -d '{
    "name": "Worker Dashboard",
    "workingDir": "~/projects/tmuxplexer",
    "command": "./tmuxplexer --watcher"
  }'

Shows: status, context usage, working directory, git branch.

References

• handoff-format.md - Worker handoff notes
• model-routing.md - Model selection