Bridge

A local-first operator hub for AI agent sessions — typed todos, blocking decisions, and a debounced dispatch engine, exposed to agents over MCP.

When several coding-agent sessions run in parallel, their "needs a human" moments scatter across terminals and get lost. Bridge collects them in one place: agents file typed todos and raise blocking decisions via MCP tools, the operator works through them in a fast dark-mode console, and every answer, decline, and comment flows back into the next agent session automatically.

Todos (list + kanban)	Decisions (focus mode)

How it works

Two planes of truth:

• Operator plane — actions in the console apply instantly (a completed todo flips to done the moment you click).
• Agent plane — the event an agent sees goes through a changes queue with a 5-second debounce and one-click undo, per-project (or global) freeze, and automatic holds while a todo's blockers are unresolved. A session long-polling await_decision resumes the moment its answer dispatches.

Decisions carry options, a recommendation, consequence/reversibility notes, an expiry, and a discuss thread — the operator can push back and the waiting session replies live instead of resuming blind.

Features

• 9 MCP tools — add_todo, complete_todo, comment_todo, await_todo, get_inbox, request_decision, await_decision, cancel_decision, reply_discussion
• Typed, stateful todos — type / action-vs-fyi / priority, open → doing → blocked → done, PR/branch/issue/worktree metadata, comments, blockers, kanban with drag-and-drop
• Session hooks (Claude Code) — a SessionStart hook injects the project's unconsumed feedback into new sessions; a Stop hook enforces that follow-ups get recorded
• Hardened for daemon life — poison changes quarantine after 3 failed dispatches instead of crash-looping; structured JSON-lines logs; hourly retention pruning + daily VACUUM INTO backups; timing-safe bearer auth; read/mutation guards built on origin + fetch-metadata checks; every entity-write + queue-stage pair is one SQLite transaction
• Zero-dependency frontend — vanilla ES modules, no build step, no external requests; SQLite (better-sqlite3, WAL) + Express + TypeScript on the server

Quickstart

npm install && npm run build
node dist/index.js            # or: ops/setup.sh  (launchd service on macOS)

• Console: http://localhost:4319 · data lives in ~/.bridge/
• The server binds loopback (plus your Tailscale IP when present) — never 0.0.0.0.
• A bearer token is generated into ~/.bridge/config.json on first boot.

Wire an agent (Claude Code):

claude mcp add --transport http bridge http://localhost:4319/mcp \
  --header "Authorization: Bearer <token from ~/.bridge/config.json>"

Scripted reads need the same header; the browser console authenticates via same-origin checks automatically.

Testing

433 tests across unit, integration, and jsdom UI suites, plus a protocol-level e2e harness (npm run e2e:server) and a real-browser e2e flow (npm run e2e:ui). Two immovable acceptance-test gates pin the core feature set and the hardening semantics.

Provenance

Built in a spec → plan → adversarial-review pipeline with Claude (Anthropic) and Codex (OpenAI) as sparring partners — each artifact reviewed by a model that didn't write it. Co-author trailers are preserved in the history on purpose.

License

MIT