GGPrompts Terminals - Worker Spawning
Spawn and manage Claude workers via TabzChrome API.
MCP Tools (Preferred)
| Tool | Purpose |
|---|---|
tabz_spawn_profile |
Spawn using saved profile |
tabz_list_profiles |
List available profiles |
tabz_list_categories |
List profile categories |
# Spawn worker with profile
tabz_spawn_profile(
profileId="claude-worker",
workingDir="~/projects/.worktrees/ISSUE-ID",
name="ISSUE-ID"
)
REST API
Spawn Terminal
TOKEN=$(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
# 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
curl -s -X DELETE "http://localhost:8129/api/agents/$SESSION" \
-H "X-Auth-Token: $TOKEN"
Git Worktrees
Worktrees enable parallel workers on same repo.
# 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):
git worktree add ".worktrees/ISSUE-ID" -b "feature/ISSUE-ID"
Dependency Initialization
Worktrees share git but NOT node_modules. Initialize before spawning:
INIT_SCRIPT=$(find ~/plugins ~/.claude/plugins ~/projects/TabzChrome/plugins -name "init-worktree.sh" -path "*spawner*" 2>/dev/null | head -1)
$INIT_SCRIPT ".worktrees/ISSUE-ID"
| Detected | Action |
|---|---|
| package.json | npm ci / pnpm / yarn / bun |
| pyproject.toml | uv pip install -e . |
| requirements.txt | uv pip install -r |
| Cargo.toml | cargo fetch |
| go.mod | go mod download |
Sending Prompts
Wait for Claude to boot (8+ seconds), then use the tabz_send_keys MCP tool:
tabz_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:
mcp-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
| Setting | Value | Why |
|---|---|---|
BEADS_WORKING_DIR |
Main repo path | Beads MCP finds database |
| Wait time | 8+ seconds | Claude boot time |
Dashboard
Monitor workers with tmuxplexer:
curl -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