Guidance for Claude Code (and other agents) working in this repository.
squish-mcp is a multi-agent message bus exposed as an MCP server. One
long-lived process holds a SQLite DB and an in-process event emitter; multiple
AI coding agents connect over Streamable HTTP and coordinate through direct
messages, broadcasts, and a shared task list. See README.md for the
user-facing tool reference and config snippets.
npm install
npm run build # tsc → dist/
npm test # vitest run (the source of truth — run before claiming done)
npm run test:watch # vitest watch
npm run typecheck # tsc --noEmit (strict mode; keep it clean)
npm run dev # node --watch on src/index.ts
node dist/index.js # run the built server (PORT=4319, HOST=127.0.0.1 by default)There is no linter/formatter configured. Match the existing style.
Request flow: index.ts (HTTP) → per-agent McpServer (mcp.ts) → tool
handlers (tools/*) → db.ts (SQLite) + events.ts (emitter).
These are load-bearing decisions — flag before deviating:
- One shared process, HTTP transport. Not stdio-per-agent. Agents share one DB and one event stream. Don't add per-agent process spawning.
- Identity is fixed per connection. The caller is the
x-agent-idrequest header, read inidentity.tsand bound into every tool handler closure inmcp.ts/tools/index.ts. Never take the sender/claimer identity from a tool argument — that would let agents impersonate each other. Requests without the header are rejected (401); a session whose header later changes is rejected (403). - SQLite + WAL.
openDb()setsjournal_mode=WAL,synchronous=NORMAL. Persistence uses Node's built-innode:sqlite(DatabaseSync) — no native addon, no compile step. It's synchronous — noawaiton DB calls. This is also why the concurrency guarantees work: writes serialize naturally. We acquire it viaprocess.getBuiltinModule("node:sqlite")indb.ts(not a static import) so bundlers/test runners don't choke on thenode:-only specifier. Transactions use theinTransaction(db, fn)helper indb.ts(node:sqlite has no.transaction()like better-sqlite3 did). - Race-safety lives in SQL, not JS.
claim_taskis a single guardedUPDATE ... WHERE status='pending' AND <deps completed>and checkschanges(). Don't replace it with read-then-write logic. - Long-poll, not WebSocket.
wait_for_messagechecks the DB, then awaitsBusEvents.waitForMessage(agentId, timeout), then re-queries. The emitter is keyed by agent ID; DB writes trigger the wake viaevents.publish(..., recipients). - SSE is a separate concern.
GET /eventssubscribes to the same emitter and filters per subscriber (BusEvents.isRelevantTo). It is for non-MCP clients (plugins/dashboards), not for MCP traffic. - Timestamps are unix epoch milliseconds (integers) everywhere.
- ESM + NodeNext. Relative imports use explicit
.jsextensions (compiled output), even though the source is.ts. Keep this — it's required, not a typo. - Tools are registered in
src/tools/{agents,messages,tasks}.ts, each with a ZodinputSchemaand a tight, model-facingdescription. Results go back as JSON text viajsonResult(...)(tools/_shared.ts) — nooutputSchema, for broad client compatibility. - Row vs. domain types (
types.ts):*Rowmirrors SQLite columns (JSON as string, nulls as| null);rowToMessage/rowToTaskproduce the public shapes (parsed metadata,is_broadcast, etc.). Convert at the boundary. - Read state is per-recipient. Direct messages use
messages.read_at; broadcasts use themessage_readstable.queryInboxunifies both — reuse it rather than writing new inbox SQL. - Logging is
pinoviasrc/logger.ts. Use it, notconsole.log.
- Tests pair real MCP
Clients with real per-agent servers overInMemoryTransport, sharing one in-memory DB (test/helpers.ts:createBus,connectAgent,call). This exercises Zod validation and result serialization, not just raw SQL — prefer it for new tool tests. connectAgentupserts the agent (mirroring the HTTP identity middleware) solist_agents/broadcastsee it.- When adding a tool, add a test in the matching
test/*.test.ts. Keep the acceptance behaviors green: per-recipient read state, broadcast exclusion, prompt long-poll wake, clean timeout, and the 50-wayclaim_taskrace.
- Don't
awaitnode:sqlitecalls —DatabaseSyncis synchronous. .get()/.all()returnRecord<string, SQLOutputValue>; cast row results withas unknown as SomeRow(a directas SomeRowwon't compile).changes/lastInsertRowidare typednumber | bigint— wrap inNumber()when summing or comparing.:memory:DBs can't exercise WAL; the WAL assertion is via the real-file path.- Don't add a static
import ... from "node:sqlite"— use the existingprocess.getBuiltinModulehandle indb.ts, or vite-node will fail to resolve it. - New SSE event types must be added to
BusEvent(events.ts), theeventPayloadswitch (index.ts), andisRelevantToif they need targeting. - Env vars:
AGENT_BUS_DB_PATH,PORT,HOST,LOG_LEVEL. - Scope guardrails (don't build without asking): auth beyond
x-agent-id, TLS, multi-host/clustering, first-class threading (usemetadata.in_reply_to), a UI. - Ask before adding any runtime dependency. Current set:
@modelcontextprotocol/sdk,zod,pino(SQLite is built into Node — no dependency).