Skip to content
Conduit

mcp server

thread

A local board for Claude Code: Claude records tasks and asks its questions and reviews on cards, you answer them together, and work with acceptance criteria is not marked done until you approve. Side

ahmed0thman/threadcommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 21, 2026

thread

In a long Claude Code session, it is easy to miss a question or lose track of work awaiting your review.

thread gives that work a local board, instructs Claude to record tasks and questions, lets you send answers together, and refuses Claude's move of a task card with acceptance criteria to done until a review is approved on the board.

A Claude Code plugin. Local board, plain Node, no runtime dependencies. Early release.

Watch it as a 20-second GIF.

Staged with invented data (a fictional shop, acme-shop): the board is real, Claude's side is scripted through the plugin's own functions; thread 0.22.0, waking off. Task capture follows Claude's instructions; the approval gate is enforced for task cards with acceptance criteria.

Install · First use · Documentation · Limits

Release License: MIT Test

Install and first use

Install

Requirements:

  • Node 20 or newer. The test suite passes on Node 20, 22 and 24; the author uses 24.
  • Claude Code (tested on 2.1.289 and 2.1.299), with the standalone claude CLI on your PATH. Threads run that CLI in the background, so the IDE extension alone is not enough.
  • It works in the terminal and in the IDE extension's chat panel; it has not been tested in the Claude Desktop app. What was run, and on which versions, is on the evidence page.
claude plugin marketplace add ahmed0thman/thread
claude plugin install thread@thread-marketplace

Restart Claude Code, or reload the editor window, so the plugin loads. Updating, trying a clone and the one-time setup are in the docs.

To get new releases by themselves, turn on auto-update (it is off by default for this marketplace): /plugin, Marketplaces, thread-marketplace, Enable auto-update. Without it, and unless you turn on the update check (off by default), nothing tells you a release exists; the docs show the two commands that update by hand.

First use

This walkthrough shows the hook that matters most. Ask Claude for two tasks in one message, one of them with acceptance criteria, and tell it to ask you when it is unsure:

Add two tasks. First: fix the rounding in the cart total; it is done when cart and checkout show the same total with any coupons and a regression test covers two stacked coupons. Second: rename the "moderator" role to "agent" in the UI copy. Ask me whatever you are unsure about.
  1. Claude is told to put each task on the board before it starts. Open the board with /thread:board: it opens the board in your browser.
  2. When Claude needs you (a question, a choice, a to-do or a review) it raises a waiting item on that card and writes one line in the chat, such as Waiting on you: c2.w1. The board shows a red Waiting for you count; open the Waiting view to see both items.
  3. Answer both, on their cards. An answer is a draft until you press Send N answers in the bar at the bottom, which sends every draft together.
  4. The answers reach Claude with your next message in that session, or at once when waking is on.
  5. Ask Claude to finish the card with criteria. Its move to done is refused until you approve a review item on that card; when Claude raises the review, answer Approve, and it moves the card.

For a side thread (a background session that reports back only when you ask), see the thread quick start. Everything works with its defaults; /thread:setup is optional.

What installing changes

  • Claude receives the plugin's board instructions at session start: put each task on the board before starting it, and send every question, review or to-do through a waiting item. See How Claude uses thread.
  • Tracking is on by default. To use only side threads, run /thread:setup and choose threads only (chat-only mode): no cards, no waiting items, and Claude is told only about threads.
  • Answers arrive with your next message in the session that asked, unless you turn waking on in /thread:setup.
  • The plugin adds an MCP server and five hooks, and keeps cards and threads in its data directory on your machine (or in .claude/thread/ if you opt in).
  • Nothing leaves the machine from the board: it listens on 127.0.0.1 only, needs an access token and makes no network calls. After an update, the first session and the board say so once, with the release's changelog entry (no network).
  • A check for a new release is off by default (updateCheck, asked in /thread:setup).
  • What Claude sessions send to Anthropic, and what delegation lanes send to their providers, is unchanged.

Short tour

Three things thread does beyond the demo above.

Decisions answered together

A question, choice, to-do or review stays on the card it belongs to. Open the Waiting view, answer across cards, and one Send delivers everything. See Waiting items.

Side threads that report back only when asked

/thread:new <task> starts a background Claude session from a short brief. Follow it from the board, continue it, and pull its digest (Happened, Decided, Changed, Open) into the main session with /thread:report. See Side threads.

Runs linked to their cards

A sub-agent call whose description starts with the card id, or a thread on a Codex, OpenCode, Antigravity or Claude lane, shows its prompt, live steps and report on that card. See Task and idea pages and Delegation lanes.

Limits and data flow

  • Capture is instructed, not enforced. Claude is told to record tasks and questions, and nothing forces it: a task it never records is not on the board, and a question asked only in the chat is not either. Instructed or enforced lists which is which.
  • The approval gate covers task cards with acceptance criteria. board_update refuses to move such a card to done until an approval is recorded on this machine's board. It does not cover cards without criteria. You can move any card yourself on the board; one with criteria is then marked not verified. The board's API accepts any request that carries the token, and Claude is not shown the board token or the tunnel's token in a tool result (/thread:board opens your browser itself, with a one-time code, and the remote link is on the board and in a file, not in the answer), but an agent with shell access could read board.token, board-link.txt or tunnel-link.txt from the data directory and record an approval itself: the gate guards the normal path, it is not a sandbox. The confirmation codes do go to Claude in the tool's reply.
  • Thread cards cannot carry acceptance criteria. Reporting a thread returns its digest to the main session without needing your approval, and ending a thread needs none.
  • A write thread edits the same working tree as the main session, at the same time.
  • Read threads are read-only because of the CLI flags the plugin passes. That is not a sandbox: a command your own allow rules approve by name still runs.
  • The board is local. It listens on 127.0.0.1, needs a token, checks Host and Origin on writes and makes no network calls.
  • The opt-in update check calls GitHub. With updateCheck on, the MCP server asks api.github.com once a day which release is the latest: a plain request that carries nothing about you or the project.
  • The opt-in tunnel uses Cloudflare. /thread:board --tunnel lasts 12 hours and has its own token and route limits.
  • Claude and the lanes still talk to their providers. Claude sessions send context to Anthropic; a lane sends its brief and files to Codex, Antigravity, OpenCode or another Claude session under that provider's terms.
  • Stored unencrypted. Card text and thread replies sit in the data directory, owner-only on macOS and Linux.
  • Tokens, measured once. In the author's one real test (two runs each), a side thread cost about 66% more than answering a medium side question inline, and about 29% less than a fresh built-in sub-agent on a big audit with two follow-ups. One repository, one model. It is not a reason on its own to install thread. See the evidence.
  • Not tested: drag and drop between custom stages with a real browser, the clipboard write of Copy report, /thread:setup in a live session, --full together with --agent, threads started from the board with the real CLI, a real browser opener launch on each platform (open, xdg-open, cmd /c start; only a stand-in opener has run), real Codex and OpenCode lanes with live steps (the relays are fakes in the tests), screen readers, Windows.

More in Security.

Evidence

All of it is the author's own; no outside user reports exist yet. Details, dates and the checks not run are on the evidence page.

  • Automated suite: node --test runs 1392 tests, all passing on 0.24.0 on Node 20, 22 and 24 in CI, together with claude plugin validate .. The CI workflow runs both on pushes to main and on pull requests.
  • The gate and the answers, on 0.22.0, for real (details): one fresh Claude Code 2.1.299 session in a scratch project, whose first turn asked whether the plugin's guide had arrived and which was then given two tasks with no mention of the board. Claude put both on the board before editing and raised one review item (the second task needed none, so sending two answers at once was not shown). The answer, sent through the board's own route, reached the next turn; asked in the chat to mark the card done, Claude was refused; after an approval through the same route, the move went through. One run, one model.
  • Real Claude Code checks, on record (details):
    • a lean thread run on 0.7.0 (2026-10-13);
    • how Claude Code reports a sub-agent run to a plugin, on Claude Code 2.1.289 (2026-10-14);
    • first runs of the Codex, Antigravity, OpenCode and Claude lane relays, and the lanes through the plugin (2026-10-14);
    • waking an idle session, on Claude Code 2.1.299 (2026-10-14).
  • Token result, both ways: Token use, measured once.

Documentation

The full index groups every feature by what you want to do. By page:

Latest release

0.24.0 (2026-10-22)

  • Work on a Codex, OpenCode or Claude lane shows on its task card like a sub-agent run, with live steps and the report.
  • Claude is no longer shown the board's token: /thread:board opens the board in your browser itself.
  • You hear about updates: "Updated to X" once with What's new, how to turn on auto-update, and an opt-in daily check for a newer release.

All releases: CHANGELOG.md.

Contributing, support, credits and licence

  • Contributing, the layout and the done test: CONTRIBUTING.md.
  • To report a problem, open an issue on GitHub.
  • Delegation lanes are built on the delegate skills by Ahmed Nagdy (MIT), which set up the lanes and run a task through Codex, Antigravity, OpenCode or Claude Code. thread only reads their lane settings and calls their relay, so install them from his repository to use lanes. Thank you, Ahmed.
  • MIT licence, see LICENSE.
↑↓ navigate openesc close