---

name: terminals description: | TabzChrome terminal spawning and worker management patterns. Use when spawning workers, managing terminals, or setting up worktrees. Trigger with "spawn worker", "create terminal", "worktree setup". model: haiku allowed-tools: Bash, Read, mcp__tabz__*

Terminals - Worker Spawning

Spawn and manage Claude workers via TabzChrome API.

MCP Tools (Preferred)

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

REST API

Spawn Terminal

CopyTOKEN=$(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

Copy# 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

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

Git Worktrees

Worktrees enable parallel workers on same repo.

Copy# 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):

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

Dependency Initialization

Worktrees share git but NOT node_modules. Initialize before spawning:

CopyINIT_SCRIPT=$(find ~/plugins ~/.claude/plugins ~/projects/TabzChrome/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 use the tabz_send_keys MCP tool:

Copytabz_send_keys(
    terminal="BD-xyz",  # Terminal name or ID
    text="Complete beads issue BD-xyz. Run: bd show BD-xyz --json",
    delay=600  # ms before Enter (increase for long prompts)
)

Or via mcp-cli:

Copymcp-cli call plugin_tabz_tabz/tabz_send_keys '{"terminal": "BD-xyz", "text": "Your prompt here", "delay": 600}'

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:

Copycurl -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