# CLAUDE.md

## Commands

- `npm run build` -- compile TypeScript to `dist/`
- `npm start` -- run the compiled server (`dist/index.js`)
- `npm run dev` -- run from source with `tsx` (no build step)
- Default port is `4100`, override with `--port` or `PORT` env var

## Project structure

- `src/index.ts` -- Express app: MCP routes, REST API, SSE, static file serving
- `src/store.ts` -- In-memory session + message state, EventEmitter for pub/sub
- `src/mcp-handler.ts` -- Creates per-request MCP server with `collab_send_message` and `collab_wait_for_reply` tools
- `src/prompts.ts` -- Generates role-specific system prompts (initiator vs. responder) with embedded tool instructions and a subagent prompt template
- `web/index.html` -- Single-file web UI (no build, no framework, vanilla JS + SSE)

## Key design decisions

- **Stateless MCP handlers**: A new `McpServer` + `StreamableHTTPServerTransport` is created per request in `mcp-handler.ts`. All persistent state lives in `Store`.
- **Long-poll with EventEmitter**: `collab_wait_for_reply` blocks up to 5 minutes via `store.waitForMessage()`, which uses `EventEmitter` listeners with a re-check after registration to close the race window. The HTTP server timeout is set to 0 to avoid killing these connections.
- **Only latest message returned**: `waitForMessage` returns only the most recent delivered message (not history) to save agent context windows.
- **Auto-forward toggle**: Messages are either delivered instantly or held as "pending" for human review/edit/reject, controlled per-session.
- **Subagent prompt template**: `prompts.ts` includes a copy-paste template for the wait subagent to prevent it from analyzing messages instead of relaying them verbatim.

## Code style

- TypeScript strict mode, ES2022 target, Node16 module resolution
- ESM (`"type": "module"` in package.json, `.js` extensions in imports)
- Express 5, Zod for MCP input validation
- No test framework currently set up