@bulletproof-sh/ctrl-daemon

WebSocket daemon for Ctrl / Cubicles — auto-discovers AI coding agent sessions (Claude Code, OpenAI Codex, Augment Code) and broadcasts live agent state to connected web clients. Features a full-screen animated TUI with a centered log panel showing daemon events in real time.

Requirements

• Bun — required at runtime (curl -fsSL https://bun.sh/install | bash)

Usage

# Auto-discover all installed AI coding tools (default)
npx @bulletproof-sh/ctrl-daemon

# Watch a single project directory
npx @bulletproof-sh/ctrl-daemon --project-dir /path/to/your/project

# Custom port / host
npx @bulletproof-sh/ctrl-daemon --port 3001 --host 127.0.0.1

# Choose a TUI background animation
npx @bulletproof-sh/ctrl-daemon --animation starfield

# Disable the TUI (plain text output)
npx @bulletproof-sh/ctrl-daemon --no-tui

# Don't auto-open the browser
npx @bulletproof-sh/ctrl-daemon --no-open

Options

| Flag | Default | Description | |---|---|---| | --port <number> | 3001 | Port to listen on (auto-increments if in use) | | --host <address> | 0.0.0.0 | Host/address to bind to | | --project-dir <path> | — | Watch a single project; omit to auto-discover all tools | | --idle-timeout <minutes> | 15 | Agent idle timeout in minutes | | --animation, -a <name> | random | Background animation: matrix, starfield, aurora, fireflies, life, pipes, dvd, starwars, none | | --no-tui | — | Disable TUI (also auto-disabled when not a TTY) | | --no-open | — | Don't auto-open the browser on startup | | --help, -h | — | Print usage |

Without --project-dir, the daemon auto-discovers all installed AI coding tools and watches their session directories.

If the requested port is already in use, the daemon automatically tries the next port (up to 10 attempts).

Terminal UI

When running in a TTY, the daemon displays an animated background (randomly selected from matrix, starfield, aurora, fireflies, life, pipes, and dvd) with a centered panel showing the CTRL logo, live agent/client counts, and scrolling daemon event logs. Use --animation <name> to pick a specific animation, or --no-tui to disable the TUI entirely.

The TUI handles terminal resize and restores the terminal cleanly on exit. The TUI is also automatically disabled when stdout is not a TTY (e.g. when piping output or running in CI).

Sharing your office

Run the daemon and an ngrok tunnel in parallel to share a live view with anyone:

# Terminal 1 — start the daemon
npx @bulletproof-sh/ctrl-daemon

# Terminal 2 — expose it publicly
ngrok http 3001

Then open ctrl.bulletproof.sh, go to Settings → Share Office and copy the generated link. Anyone who opens it will see your agents in real time — no auth or setup required on their end.

Note: Free ngrok URLs rotate each time you restart the tunnel. A paid ngrok plan gives you a stable domain.

WebSocket API

Connect to ws://localhost:3001/ws. The daemon broadcasts JSON messages whenever agent state changes — the same message format used by the VS Code extension's internal webview protocol.

The Ctrl web app connects here by default. You can change the URL in the app's Settings modal or by setting VITE_DAEMON_WS_URL at build time.

Health check

GET /health returns JSON with daemon status, agent count, and version:

{ "status": "ok", "agents": 3, "version": "0.0.18" }

Environment Variables

| Variable | Description | |---|---| | CLAUDE_HOME | Override the Claude home directory (default: ~/.claude) |

Crash reports use PostHog analytics.

Auto-update

On startup — and every 5 minutes in the background — the daemon checks npm for a newer version. If one is found, a notice is printed (or logged to the TUI panel):

  ⬆  Update available: v0.0.8 → v0.0.9
     Run: npx @bulletproof-sh/ctrl-daemon@latest

The check is non-blocking and fails silently if the registry is unreachable.

Note: If you're running via npx, you already get the latest version on every invocation — no manual update needed.

Development

bun install
bun run dev        # watch mode
bun run build      # compile to dist/
bun run verify     # tsc + biome + tests
bun run test       # tests only

License

BUSL-1.1