terminals

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

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