mcp-session-threads

An MCP server that turns an agent's review and decision loops into a browser board of threads you answer at your own pace — instead of a wall of text in the terminal.

When an agent has several findings, questions, or decisions for you, it posts each as its own thread on a local web board. You reply per‑thread with quick‑reply buttons or free text, dump unrelated thoughts in a side notes rail, and submit once. The agent picks up your batched feedback and responds — all on one stable local URL, with a fresh board per project.

Why

You're deep in one Claude Code session and the work piles up:

• you spot several improvement ideas at once and don't want to fork a separate session for each;

• the agent hands you ~30 review findings to work through together;

• juggling multiple sessions is a chore — and parallel agents happily crash into each other's work.

The fix is one system, one context window — but with each thread shown as its own chat, so it stays easy to keep track. You answer threads independently, at your own pace, and send your feedback back in batches. The agent keeps working in a single session; nothing forks, nothing collides, nothing gets lost in the scrollback.

Related MCP server: Lens

Install

Requires Node ≥ 18. No global install needed — run it with npx.

Claude Code

claude mcp add session-threads -- npx -y mcp-session-threads

Any MCP client

Point your client at the command npx -y mcp-session-threads (stdio transport). Or install globally:

npm i -g mcp-session-threads
mcp-session-threads   # this is the stdio MCP server

The first tool call prints the board URL — open it in your browser (default http://127.0.0.1:4517/b/<id>).

How it works

Two processes, auto‑managed:

• MCP server (mcp-session-threads, stdio) — one per client session. Exposes the tools below.

• Daemon (auto‑started on first use) — one long‑lived HTTP server on a fixed port hosting many boards and the web UI. It persists, so a board's URL never moves between restarts.

Each session resolves a stable board by key (the working directory by default), so:

• the URL is the same across restarts for a given project,

• concurrent sessions in different projects get separate boards,

• no drift, no cross‑session bleed‑over.

Boards are stored as JSON under ~/.session-threads/boards.

Web board

• Command‑center list grouped into lanes — Needs your attention, Waiting on agent, Deferred, Resolved — newest first; click one to open it full‑screen as a chat.

• Read/unread per thread: unread = still awaiting your response; cleared only when you reply or submit (never by merely viewing). Shown as a marker in the list and a pill in the full‑screen view.

• Markdown in bodies/messages — code, tables, lists, links — rendered safely (HTML escaped, javascript: links neutralised).

• Freestyle tags (high, security, question, …) shown as auto‑coloured badges.

• Quick replies inline in the chat; a click stages the reply as an editable pending bubble. Your drafts persist in the browser until you submit.

• Other notes rail, always open, for thoughts unrelated to any thread — each submission is preserved.

• Turn‑aware progress: the top bar + browser title switch between agent progress while it works and your reply progress when it's your turn; optional per‑board sounds confirm when your feedback syncs and ping when it becomes your turn.

• Keyboard: k/j next/prev thread, Enter/e open or reply, h/l scroll, r resolve, Esc leave.

Tools

Failed calls throw — the agent never falsely reports a write that didn't land.

Configuration

All optional, via environment variables:

Development

npm install
npm test        # node --test: unit (store, feedback, markdown), HTTP integration, and MCP e2e
npm run daemon  # run the HTTP daemon directly

Architecture (src/): board-store.js (model + persistence, event‑emitting), feedback.js (long‑poll hub), http-server.js (REST + SSE + static), client.js (resilient daemon client), tools.js (MCP tool wiring), mcp.js / daemon.js (entry points). The Markdown renderer (public/markdown.js) is shared by the UI and the tests.

License

MIT