open-index/open-npm huggingface dataset:
npm package: @pompeii-labs/bridge
Description: CLI for running a [Pompeii](https://pompeii.ai) 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.
Latest version: 0.1.4

# @pompeii-labs/bridge

CLI for running a [Pompeii](https://pompeii.ai) 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](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) 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.