@ai-monitor/bridge

Local gateway that bridges AI tool logs to the My AI Partner iOS app via WebSocket RPC.

Install

npm install -g @ai-monitor/bridge

Requirements: Node.js 20.x to 22.x (native dependencies are not validated on newer majors).

Quick Start

# 1. Generate config
ai-monitor-bridge init

# 2. Start the bridge daemon
ai-monitor-bridge start
# Gateway: ws://127.0.0.1:18790
# Device token: <printed to stdout — copy into iOS app>

CLI Commands

| Command | Description | |---------|-------------| | init | Generate ~/.config/ai-monitor-bridge/config.json | | start | Start daemon (gateway + Claude + Gemini watchers) | | attach <tool> [args...] | Wrap a tool with PTY logging. Supports: claude, codex, gemini, openclaw | | import cursor [--since 24h] | Import Cursor IDE session history via cursor-history | | import claude [--since 24h] | Import Claude Code JSONL history from ~/.claude/projects/ | | import gemini [--since 24h] | Import Gemini log history from ~/.gemini/ + XDG path | | import codex [--since 24h] | Import Codex history from ~/.codex/ | | status | Show spool status and bridge info | | flush | Force-flush pending spool records to cloud |

Adapter Capability Matrix

| Adapter | watch (passive) | attach (PTY) | import (batch) | |---------|:-:|:-:|:-:| | Claude Code | ✓ (JSONL watcher) | ✓ | — | | Gemini | ✓ (~/.gemini/**) | ✓ (with args) | ✓ | | Codex | ✓ (~/.codex/**, no args) | ✓ (with args) | ✓ | | OpenClaw | — | ✓ (WebSocket proxy) | — | | Cursor | — | → use import | ✓ (cursor-history) |

Configuration

Config file: ~/.config/ai-monitor-bridge/config.json

{
  "gateway": {
    "port": 18790,
    "auth": "device-token"
  },
  "upload": {
    "endpoint": "",
    "apiKey": "env:AI_BRIDGE_API_KEY",
    "batchSize": 50,
    "flushIntervalMs": 3000
  },
  "retry": {
    "maxAttempts": 8,
    "baseDelayMs": 500,
    "maxDelayMs": 60000
  },
  "spool": {
    "dir": "~/.ai-monitor-bridge/spool",
    "maxMb": 1024
  },
  "privacy": {
    "enableRedaction": true,
    "rules": ["openai_key", "aws_key", "anthropic_key", "email", "phone"]
  },
  "tools": {
    "claude": {
      "projectsDir": "~/.claude/projects",
      "hooksPort": 18791,
      "autoInjectHooks": false
    }
  }
}

Authentication Modes

device-token (default, recommended)

On first startup the bridge generates a stable device token and prints it to stdout:

[GatewayServer] Device token: a1b2c3d4-e5f6-...
[GatewayServer] Copy this token into the iOS app Settings to pair.

First-time pairing:

1. Run ai-monitor-bridge start
2. Copy the printed device token
3. In the iOS app, go to Settings → Bridge Token and paste it
4. The app will include the token in every connect handshake

Clients that do not present a valid token are rejected with PAIR_REQUIRED.

The token is persisted at ~/.config/ai-monitor-bridge/device-token (mode 0600).

token (explicit secret)

Set auth: "token" and token: "<secret>" to require a specific secret:

{
  "gateway": {
    "port": 18790,
    "auth": "token",
    "token": "my-secret-token"
  }
}

Note: If auth is "token" but token is empty, the bridge will refuse to start.

none (development only)

No authentication — any local process can connect. A warning is printed on startup.

iOS Integration

The iOS app connects to ws://127.0.0.1:18790 by default (configurable in Settings).

Supported RPC methods:

| Method | Description | |--------|-------------| | connect | Handshake (required first) | | sessions.list | List AI partner sessions | | sessions.events | Fetch canonical timeline history for a session | | health | Returns { status: "ok", version: "1.0" } | | chat.send | Proxied to upstream OpenClaw gateway | | chat.abort | Proxied to upstream OpenClaw gateway | | bridge.status | Returns adapter status, spool stats, uptime |

Cursor Import

cursor-history is optional. If it is not installed, the bridge falls back to direct Cursor DB reads (state.vscdb) when better-sqlite3 is available.

npm install -g cursor-history
ai-monitor-bridge import cursor --since 24h

Spool & Reliability

Events are persisted to ~/.ai-monitor-bridge/spool/spool.db (SQLite WAL mode). The attach command also uses the spool — events survive bridge restarts. If better-sqlite3 is unavailable at runtime, the bridge falls back to an in-memory spool (non-persistent).

Publishing

Use the publish script to release both @ai-monitor/types and @ai-monitor/bridge:

# Patch release (default)
./scripts/publish.sh

# Minor / major
./scripts/publish.sh minor
./scripts/publish.sh major

# Publish current version without bumping (e.g. retry a failed publish)
./scripts/publish.sh --no-bump

The script publishes @ai-monitor/types first (since bridge depends on it), then @ai-monitor/bridge.