ai-cli-bridge: Instructions file for Claude Code

CLAUDE.md — ai-cli-bridge

What This Is

HTTP bridge server wrapping Claude Code CLI and Codex CLI behind an Express API. Uses Max/Pro subscriptions instead of per-token API keys. Designed to deploy on any VPS behind a reverse proxy or Cloudflare Tunnel.

Stack

• Runtime: Bun, TypeScript, ES modules
• Framework: Express 4
• Package manager: bun
• Process manager: systemd
• Tunnel: Cloudflare Tunnel (cloudflared)
• No database — JSON file persistence (data/keys.json, data/usage.json, data/logs.json)

Project Layout

src/
  server.ts           — Express app, routes, middleware, security headers
  config.ts           — Env var parsing + defaults
  keys.ts             — KeyManager: hashed key CRUD, usage tracking, limits, request logs
  middleware/auth.ts   — Per-user key auth + admin auth (timing-safe)
  utils/sse.ts        — SSE helpers (initSSE, sendSSEEvent, sendSSEError, sendSSEDone)
  providers/
    claude.ts         — Claude Code CLI wrapper (execFile + spawn for streaming)
    codex.ts          — Codex CLI wrapper (execFile + spawn for streaming)
public/
  admin.html          — Dashboard markup
  admin.css           — Dashboard styles
  admin.js            — Dashboard logic
dist/                 — Compiled JS (gitignored)
data/                 — Runtime data (gitignored, 0o600 permissions)

Commands

bun dev               # Dev server with watch
bun run build         # TypeScript compile (tsc)
bun start             # Run via bun
bun start:prod        # Run compiled JS (bun dist/server.js)

Build & Deploy

bun run build
rsync -avz --exclude node_modules --exclude .env --exclude data --exclude .git \
  ./ <YOUR_SERVER>:/path/to/ai-cli-bridge/
ssh <YOUR_SERVER> "systemctl restart ai-cli-bridge"

Static-only changes (public/) don't need a server restart.

See DEPLOY.md for full reference.

Architecture

• CLI wrapping: execFile() spawns CLI for non-streaming, spawn() for streaming. Both use array args (no shell injection).
• Endpoint-based routing: /generate → Claude CLI, /generate-codex → Codex CLI. Both support stream: true for SSE responses.
• Auth: SHA-256 hashed keys with crypto.timingSafeEqual. Raw keys never stored — shown once at creation. req.keyHash on request object, never req.rawKey.
• Limits: Per-key: requests/day, requests/month, tokens/month, cost/day, cost/month. All default 0 (unlimited).
• Usage tracking: In-memory with 30s dirty-flag flush to disk. Daily entries pruned >90 days, monthly >12 months.
• Request logs: Append-only in logs.json, capped at 1000 entries FIFO, prompts truncated to 200 chars.
• Admin dashboard: Static HTML/CSS/JS served via express.static before admin auth middleware. Uses sessionStorage for admin key.