@pompeii-labs/bridge

CLI for running a Pompeii agent bridge on your local machine. The bridge connects your local dev environment to Pompeii so AI agents can work on your codebase when @mentioned in conversations.

Install

npm i -g @pompeii-labs/bridge

Requires cloudflared for the tunnel.

brew install cloudflared

Quick start

pompeii bridge start

On first run this launches interactive setup, which asks for:

1. Pompeii API key - from your workspace settings at pompeii.ai
2. Webhook secret - from the agent config page
3. Repository paths - local paths the agent can access
4. Backend - Claude Code or OpenAI Codex

Config is saved to ~/.pompeii/. After setup, the bridge starts as a background daemon with a Cloudflare tunnel and automatically registers the webhook URL with Pompeii.

Commands

pompeii bridge setup    # interactive config
pompeii bridge start    # start daemon + tunnel (runs setup if no config)
pompeii bridge stop     # stop the daemon
pompeii bridge status   # show PID, port, tunnel URL, active requests
pompeii bridge logs     # tail ~/.pompeii/bridge.log

Options

pompeii bridge start --port 3001    # custom port (default: 3001)
pompeii bridge logs --lines 100     # number of lines to show (default: 50)

Config

All config lives in ~/.pompeii/:

| File | Contents | |------|----------| | config.json | repos, backend, port, tunnel settings | | .env | POMPEII_API_KEY, WEBHOOK_SECRET | | daemon.json | runtime state (PID, tunnel URL, start time) | | bridge.log | daemon stdout/stderr |

Environment variables always take precedence over file config:

WEBHOOK_SECRET, POMPEII_API_KEY, REPOS, BACKEND, PORT,
MAX_TURNS, MAX_CONCURRENT, ALLOWED_TOOLS, POMPEII_API_URL

How it works

1. pompeii bridge start spawns the bridge server as a detached background process
2. The server starts a Cloudflare quick tunnel to get a public URL
3. The tunnel URL is registered with the Pompeii API as your agent's webhook
4. When someone @mentions your agent in Pompeii, the platform sends a webhook to the tunnel
5. The bridge runs the request through Claude Code (or Codex) against your local repos
6. Responses stream back to Pompeii via SSE

Development

cd bridge
bun install
bun run dev

For local dev without the daemon, set env vars directly:

WEBHOOK_SECRET=xxx POMPEII_API_KEY=xxx REPOS=/path/to/repo TUNNEL=1 bun run dev

Publishing

cd bridge
npm publish --access public

The prepublishOnly script runs tsc automatically before publish.