---

name: terminals description: "Spawn and manage terminal tabs via TabzChrome REST API. Use when spawning workers, creating terminals programmatically, setting up worktrees for parallel work, or crafting prompts for Claude workers."

TabzChrome Terminal Management

Spawn terminals, manage workers, and orchestrate parallel Claude sessions.

Spawn API

CopyTOKEN=$(cat /tmp/tabz-auth-token)
curl -X POST http://localhost:8129/api/spawn \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $TOKEN" \
  -d '{"name": "Worker", "workingDir": "~/projects", "command": "claude"}'

Response:

Copy{
  "success": true,
  "terminalId": "ctt-default-abc123",
  "tmuxSession": "ctt-default-abc123"
}

Spawn Options

Parallel Workers with Worktrees

Copy# Create isolated worktree (bd handles beads redirect automatically)
bd worktree create feature-branch

# Spawn worker there with BEADS_WORKING_DIR for MCP tools
PROJECT_DIR=$(pwd)
curl -X POST http://localhost:8129/api/spawn \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $TOKEN" \
  -d "{\"name\": \"Feature Worker\", \"workingDir\": \"../feature-branch\", \"command\": \"BEADS_WORKING_DIR=$PROJECT_DIR claude\"}"

Key: BEADS_WORKING_DIR tells the beads MCP server where to find the database. Point it to the main repo, not the worktree.

Worker Prompts

Keep prompts simple - workers are vanilla Claude:

CopyFix the pagination bug in useTerminalSessions.ts around line 200.
Run tests when done: npm test
Close the issue: bd close TabzChrome-abc --reason="done"

Avoid prescriptive step-by-step pipelines. Let Claude work naturally.

Worker Management

List Workers

Copycurl -s http://localhost:8129/api/agents | jq '.data[]'

Find by Name

Copycurl -s http://localhost:8129/api/agents | jq -r '.data[] | select(.name == "V4V-ct9")'

Get Session ID

CopySESSION=$(curl -s http://localhost:8129/api/agents | jq -r '.data[] | select(.name == "V4V-ct9") | .id')

Kill Worker

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

Send Prompt via tmux

Copytmux send-keys -t "$SESSION" -l "Your prompt here"
sleep 0.5
tmux send-keys -t "$SESSION" Enter

References

See references/ for details:

• spawn-api.md - Full API reference
• worktree-setup.md - Git worktree patterns
• worker-prompts.md - Prompt crafting guidelines