Spawn API

Spawn terminals programmatically via REST API

POST /api/spawn

Spawn a new terminal tab with optional custom name, working directory, and startup command.

⚠️ Authentication Required: This endpoint requires an X-Auth-Token header with the token from /tmp/tabz-auth-token.
Parameter Type Required Description
X-Auth-Token (header) string Yes Auth token from /tmp/tabz-auth-token
name string No Display name for the tab (default: "Claude Terminal")
workingDir string No Starting directory (default: $HOME). Supports ~
command string No Command to run after shell ready (~1.2s delay)

GET /api/browser/profiles

Get all terminal profiles from Chrome storage. Useful for automation and discovering available profiles.

curl example 
$ curl http://localhost:8129/api/browser/profiles

Response

{ "success": true, "profiles": [ { "id": "claude-code-12345", "name": "Claude Code", "category": "AI Assistants", "command": "claude --dangerously-skip-permissions", "workingDir": "", "fontSize": 16, "fontFamily": "JetBrains Mono", "themeName": "high-contrast" }, // ... more profiles ], "defaultProfileId": "claude-code-12345", "globalWorkingDir": "~/projects" }

Note: Profiles with empty workingDir inherit from globalWorkingDir.

GET /api/browser/tabs

List all open browser tabs with accurate active tab detection. Uses extension API for real-time accuracy.

curl example 
$ curl http://localhost:8129/api/browser/tabs

Response

{ "success": true, "tabs": [ { "id": 1762556520, "title": "GitHub - TabzChrome", "url": "https://github.com/GGPrompts/TabzChrome", "active": true, "windowId": 1 }, // ... more tabs ], "activeTabId": 1762556520 }

Note: Tab IDs are real Chrome tab IDs (large integers), not simple indices. The active field and activeTabId accurately reflect which tab the user has focused.

Basic Examples

curl examples 
# Get auth token first
$ TOKEN=$(cat /tmp/tabz-auth-token)

# Simple terminal
$ curl -X POST http://localhost:8129/api/spawn \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $TOKEN" \
  -d '{}'

# Named terminal with directory
$ curl -X POST http://localhost:8129/api/spawn \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $TOKEN" \
  -d '{
    "name": "Project Work",
    "workingDir": "~/projects/myapp"
  }'

# Terminal with startup command
$ curl -X POST http://localhost:8129/api/spawn \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $TOKEN" \
  -d '{
    "name": "Git UI",
    "workingDir": "~/projects/myapp",
    "command": "lazygit"
  }'

Claude Code Examples

Claude Code spawn commands 
# Get auth token first
$ TOKEN=$(cat /tmp/tabz-auth-token)

# Basic Claude Code
$ curl -X POST http://localhost:8129/api/spawn \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $TOKEN" \
  -d '{
    "name": "Claude",
    "workingDir": "~/projects/myapp",
    "command": "claude"
  }'

# Claude Code with full permissions
$ curl -X POST http://localhost:8129/api/spawn \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $TOKEN" \
  -d '{
    "name": "Claude (Auto)",
    "workingDir": "~/projects/myapp",
    "command": "claude --dangerously-skip-permissions"
  }'

# Claude Code explore agent
$ curl -X POST http://localhost:8129/api/spawn \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: $TOKEN" \
  -d '{
    "name": "Claude Explore",
    "workingDir": "~/projects/myapp",
    "command": "claude --agent explore --dangerously-skip-permissions"
  }'

Interactive Claude Code Launcher

Build Claude Code commands dynamically. Requires TabzChrome backend running on localhost:8129.

Security Token

Required for the Spawn button. Get your token from Tabz Settings → API Token, or run: cat /tmp/tabz-auth-token

Configure Your Command

Generated Command:

claude

Tab Name:

Claude

curl Command:

TUI Tools Quick Launcher

Launch popular TUI tools in TabzChrome with one click. Tools inherit the working directory from above.

Response Format

{ "success": true, "terminal": { "id": "ctt-Claude-a1b2c3d4", "name": "Claude", "terminalType": "bash", "ptyInfo": { "useTmux": true, "tmuxSession": "ctt-Claude-a1b2c3d4" } } }

Shell Function

Add to your .bashrc or .zshrc for quick terminal spawning:

.bashrc / .zshrc 
# Spawn a terminal in TabzChrome
tabz-spawn() {
  local name="${1:-Terminal}"
  local dir="${2:-$PWD}"
  local cmd="${3:-}"
  local token=$(cat /tmp/tabz-auth-token 2>/dev/null)

  if [[ -z "$token" ]]; then
    echo "Error: TabzChrome backend not running (no auth token)"
    return 1
  fi

  curl -s -X POST http://localhost:8129/api/spawn \
    -H "Content-Type: application/json" \
    -H "X-Auth-Token: $token" \
    -d "{\"name\": \"$name\", \"workingDir\": \"$dir\", \"command\": \"$cmd\"}"
}

# Quick Claude Code spawn
tabz-claude() {
  local dir="${1:-$PWD}"
  tabz-spawn "Claude" "$dir" "claude --dangerously-skip-permissions"
}

# Usage:
$ tabz-spawn "My Terminal" ~/projects
$ tabz-spawn "Git" ~/projects/myapp lazygit
$ tabz-claude ~/projects/myapp

JavaScript / Web Page Integration

// Token must be provided by the user (from Tabz Settings → API Token) // Store in localStorage for persistence const AUTH_TOKEN = localStorage.getItem('tabz-auth-token'); // Spawn terminal from web page async function spawnTerminal(name, workingDir, command) { if (!AUTH_TOKEN) { throw new Error('Token required - get from Tabz Settings'); } const response = await fetch('http://localhost:8129/api/spawn', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Auth-Token': AUTH_TOKEN }, body: JSON.stringify({ name, workingDir, command }) }); return response.json(); } // Example: Spawn Claude Code spawnTerminal( 'Claude Worker', '~/projects/myapp', 'claude --dangerously-skip-permissions' );

Notes