BullyBuddy#

Spawns and manages multiple Claude Code CLI sessions. Dual backend: tmux (default, sessions survive server restart) or node-pty (fallback). REST API, WebSocket streaming, web dashboard.

Setup#

1. Install the package globally:

bash

npm install -g openclaw-bullybuddy

1. Start the server:

bash

bullybuddy server

Connection info is auto-saved to ~/.bullybuddy/connection.json on startup. The /bullybuddy command reads it automatically — no env vars needed.

For remote access, start with bullybuddy server --tunnel. The tunnel URL is available via /bullybuddy url.

/bullybuddy Slash Command#

text

/bullybuddy status          - Server status & session summary
/bullybuddy list            - List all sessions
/bullybuddy spawn [cwd] [task] [group] - Create new session
/bullybuddy send <id> <text> - Send input to session
/bullybuddy output <id> [lines] - Show session output/transcript
/bullybuddy kill <id>       - Terminate session
/bullybuddy url             - Show dashboard URL (local + tunnel)
/bullybuddy audit [limit]   - View audit log
/bullybuddy transcript <id> [limit] - View conversation transcript
/bullybuddy help            - Show help

Security Notice#

• The auth token grants full control over all spawned Claude Code sessions, including sending arbitrary input. Treat it as a secret.
• The /bullybuddy url command outputs the dashboard URL with the token embedded. Do not share or log this URL publicly.
• When using --tunnel, the dashboard and API are exposed to the internet via a Cloudflare temporary URL. Anyone with the token can access all sessions remotely.
• Spawned sessions run Claude Code with your local permissions. If --dangerously-skip-permissions is enabled, Claude can execute any command without confirmation.

Authentication#

A random token is generated on each server start and saved to ~/.bullybuddy/connection.json (mode 0600). CLI and /bullybuddy auto-discover it. For the dashboard, the token is included in the URL printed on startup. The connection file is deleted on graceful shutdown.

API Overview#

All endpoints require the token via Authorization: Bearer <token> header or ?token= query parameter. All responses follow { ok: boolean, data?: T, error?: string }.

MethodEndpointDescriptionGET``/healthServer statusGET``/api/sessionsList sessions (filter by group)POST``/api/sessionsSpawn sessionGET``/api/sessions/:idSession detail with metricsDELETE``/api/sessions/:idKill sessionPOST``/api/sessions/:id/inputSend input to PTYPOST``/api/sessions/:id/resizeResize PTYPOST``/api/sessions/:id/taskSet task metadataPOST``/api/sessions/:id/muteMute notificationsPOST``/api/sessions/:id/unmuteUnmute notificationsGET``/api/groupsGroups with session countsGET``/api/summaryAggregate state counts and groupsGET``/api/browseBrowse directories (disabled by default)GET``/api/auditAudit logGET``/api/sessions/:id/transcriptConversation transcript

Spawn Request Body#

json

{
  "name": "worker-1",
  "group": "myproject",
  "cwd": "/path/to/repo",
  "task": "Implement feature X",
  "args": ["--verbose"],
  "cols": 120,
  "rows": 40,
  "skipPermissions": false
}

All fields optional. When task is provided, it is automatically sent as input when Claude reaches the idle prompt.

Note: When sending input, terminate with \r (carriage return), not \n.

WebSocket Protocol#

Connect to ws://<host>:<port>/ws?token=<token>.

Client Messages#

typefieldsdescriptionsubscribe``sessionId, cols?, rows?Receive output from sessionunsubscribe``sessionIdStop receiving outputinput``sessionId, dataSend keystrokes to PTYresize``sessionId, cols, rowsResize PTY

Server Messages#

typefieldsdescriptionsessions``sessions[]Full session list (on connect)output``sessionId, dataTerminal output chunkscrollback``sessionId, dataBuffered scrollback on subscribesession:created``sessionNew session spawnedsession:exited``sessionId, exitCodeSession terminatedsession:stateChanged``sessionId, detailedStateState transitionerror``messageError (e.g. invalid message)

State Detection#

BullyBuddy analyzes raw PTY output to detect Claude Code's state in real-time.

detailedStateMeaningstartingSession just spawned, Claude loadingworkingClaude is thinking/editing (spinner visible)permission_neededClaude waiting for user approvalidleClaude at prompt, ready for inputcompactingCompacting conversation historyerrorError detected in output

State transitions are broadcast via WebSocket and reflected in GET /api/summary.

OpenClaw Integration#

Poll GET /api/summary on an interval to check fleet status. The sessionsNeedingAttention field contains IDs of sessions in permission_needed or error state.

Remote Access#

Start the server with --tunnel to create a Cloudflare temporary URL automatically:

bash

bullybuddy server --tunnel

The tunnel URL is printed on startup and saved to ~/.bullybuddy/connection.json. Use bullybuddy url or /bullybuddy url to retrieve it anytime.

CLI Commands#

bash

bullybuddy server                          # Start server
bullybuddy server --tunnel                 # Start with Cloudflare tunnel
bullybuddy url                             # Show dashboard URL (local + tunnel)
bullybuddy spawn --name worker --group proj  # Spawn session
bullybuddy list --json                     # List sessions
bullybuddy send <id> "Fix the bug"         # Send input
bullybuddy attach <id>                     # Interactive terminal
bullybuddy kill <id>                       # Kill session
bullybuddy groups                          # List groups
bullybuddy open                            # Open dashboard

Script#

When invoked, run:

bash

{baseDir}/scripts/bullybuddy.sh $ARGUMENTS