Terminals

TabzChrome Terminal Management

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

Spawn API

bashCopy code
TOKEN=$(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:

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

Spawn Options

Parallel Workers with Worktrees

bashCopy code
# 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:

Copy code
Fix 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

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

Find by Name

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

Get Session ID

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

Kill Worker

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

Send Prompt via tmux

bashCopy code
tmux 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