tabz-terminals

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

Spawn API

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:

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

Spawn Options

| Field | Type | Default | Description | |-------|------|---------|-------------| | name | string | "Claude Terminal" | Tab display name | | workingDir | string | $HOME | Starting directory | | command | string | - | Command to run after spawn | | profileId | string | default | Profile for appearance |

Parallel Workers with Worktrees

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

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

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

Find by Name

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

Get Session ID

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

Kill Worker

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

Send Prompt via tmux

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