Enables AI agents to enqueue decision tickets for human review via a status board without blocking the agent's session.
Also known as therebelrobot/readyroom
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 12, 2026
- License
- —
What is readyroom MCP?
readyroom enables AI agents to enqueue decision tickets for human review via a status board without blocking the agent's session.
Summary generated from the project's README
About readyroom MCP server
Enqueuing decision tickets for human review without pausing an AI agent's session is what readyroom enables. It provides a bridge between autonomous agents and human supervisors by allowing agents to submit questions, optional choices, and media for inspection via a dedicated status board. This approach prevents agents from blocking their own sessions or hijacking a user's screen with modals while waiting for a response.
Developers can deploy this system using npx, Docker, or as a Cloudflare Worker. The server manages multiple agent streams, grouping tickets so users can easily identify which agent is requesting input. It features a keyboard-first interface for draining the queue and maintains an append-only approval log for auditing. The system supports attaching screenshots, audio, or video to tickets, which humans can mark up with drawing tools before sending the annotated results back to the agent.
What you can do with it
- 1Submit non-blocking decision requestsAn agent can request a human decision and immediately return to other tasks instead of waiting and holding the session open.
- 2Manage multiple agent streamsA supervisor can monitor and answer questions from several different agents through a single organized status board.
- 3Maintain an audit trailUsers can rely on a permanent record of all human-authorized actions through an unpruned log.
Written from the project's README. Every use case is checked against a quote from it.
How to install readyroom MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall readyroom MCP in Claude Code
$ claude mcp add readyroom -- npx -y readyroomInstall readyroom MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"readyroom": {
"command": "npx",
"args": [
"-y",
"readyroom"
]
}
}
}Install readyroom MCP in VS Code
.vscode/mcp.json
{
"servers": {
"readyroom": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"readyroom"
]
}
}
}Install readyroom MCP in VS Code CLI
$ code --add-mcp '{"name":"readyroom","type":"stdio","command":"npx","args":["-y","readyroom"]}'Install readyroom MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"readyroom": {
"command": "npx",
"args": [
"-y",
"readyroom"
]
}
}
}Install readyroom MCP in Codex
$ codex mcp add readyroom -- npx -y readyroomInstall readyroom MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.readyroom] command = "npx" args = ["-y", "readyroom"]
Install readyroom MCP in Gemini CLI
$ gemini mcp add -s user readyroom npx -- -y readyroomInstall readyroom MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"readyroom": {
"command": "npx",
"args": [
"-y",
"readyroom"
]
}
}
}Configuration
READYROOM_STATE_DIRREADYROOM_STREAM
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachabletherebelrobot/readyroom is public and reachablegithub.com/therebelrobot/readyroom ↗Pass
- Package names this repository as its sourcereadyroom names therebelrobot/readyroom as sourcenpmjs.com/package/readyroom ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for readyroomnpmjs.com/package/readyroom/v/0.2.0#provenance ↗Pass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-12github.com/therebelrobot/readyroom ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from readyroomPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubreadyroom
The bridge runs the ship. The ready room decides.
[!WARNING] readyroom is under active development. Don't rely on it for anything that matters until v1.
What is this?
An agent that reaches a decision it should not make alone has two bad options today. It can guess, and the guess becomes fact downstream. Or it can stop and wait, which holds its session open until a human notices, and usually surfaces as a modal that hijacks whatever you were doing.
readyroom gives it a third. The agent writes a ticket — one question, optional choices, minimal context — and goes back to work. You drain the tickets from one page when you get to them. The page groups them under the agent that asked, so you always know who is waiting on you, and the agent collects the answer the next time it asks.
The name is the design. On a ship, the bridge is where the work happens and the ready room is where the captain steps away to decide something that should not be decided in the noise. The whole invariant is N agents, one interrupt channel: however many agents you run, they share one place to ask and one place for you to answer.
Why readyroom
- No agent ever blocks.
ask_humanenqueues a ticket and returns in under 200 ms. A blocking tool holds the MCP session open and wedges the client the moment you step away from the keyboard for twenty minutes. - The queue survives a restart. Tickets are written atomically to disk, or to a single Durable Object on the Worker. A restart that forgot pending tickets would mean an agent waiting forever on a question nobody can see any more.
- You know which agent is asking. Tickets are grouped by stream — the agent that asked — with the newest stream first. A flat list of questions from four agents is not a queue you can drain; it is a pile.
- It never takes over your screen. There is no modal and no focus stealing. The page is a status board, not a chat log: it shows what is waiting and clears when you have answered.
- Draining is keyboard-first.
j/kto move,1-5to pick an option,Enterto submit,uto undo. A queue with only a mouse is the slow path, and the point of a queue is that it drains quickly. - The log is append-only and never pruned. An approval log is the only record that a human authorised something, so it is kept in full. That is what a log is.
- Three ways to run it, one program.
npxfor one machine, Docker for an always-on box, a Cloudflare Worker for when your agents cannot reach either.
Screenshots
The page is one flow — the human draining the queue — and one authenticated role, so every capture is a state of that single flow rather than a role of its own. A few representative moments, desktop first:
There is also an empty board, an inline per-card validation error, and a failed-load banner —
the page is captured at 1280x800 (desktop) and 390x844 (the two mobile-* shots). A full set
of every screen and state, with a one-line description of each, is in
docs/screenshots/MANIFEST.md — regenerate the lot with
npm run screenshots
which starts its own isolated readyroom on :8972, drives each state, and tears it down. For how
to actually use each of these screens, see docs/USAGE.md.
Vocabulary
These words are used exactly, in code, comments, tool descriptions, and docs. No synonyms.
- ticket — one pending request:
{ id, stream, question, options, context, urgency, status, created_at, expires_at }. - stream — which agent asked. Defaults to
$READYROOM_STREAM, elsebasename(cwd). - drain — the human answering tickets from the page.
- readyroom page — the single HTML page served at
GET /.
The tool names (ask_human, wait_for_answer, list_pending, cancel_ticket) are the
agent-facing contract and do not change with the product name. The product name is a separate
layer, the way ripgrep ships rg.
The one rule that matters
ask_human enqueues and returns. It never waits.
A blocking tool holds the MCP session open and wedges the client when the human is heads-down
for twenty minutes. Enqueue-then-poll keeps the transport healthy. ask_human returns
{ id, status: "pending" } in under 200 ms.
This rule is also what makes the Worker target possible at all. A Workers invocation cannot hold a session open for twenty minutes; a request that enqueues and returns is stateless enough to run per-request on the edge. There is no blocking variant on any target.
The ask_human tool description is where the agent learns the protocol: on pending,
continue with independent work and call wait_for_answer again later; do not poll in a tight
loop.
The four MCP tools
All four tools are identical across all three targets. Only the transport differs.
ask_human
Enqueues a ticket and returns immediately.
ask_human({
question: string, // required. One sentence. What must be decided.
options?: string[], // optional. 2-5 mutually exclusive choices.
context?: string, // optional. Minimal text needed to decide. Plain text.
default_answer?: string, // optional. Used only if the ticket expires. Set it only
// when it is safe for the agent to proceed without a human.
timeout_seconds?: number, // optional. Default 1800. Max 86400.
urgency?: "low" | "normal" | "blocking", // optional. Default "normal".
stream?: string, // optional. Overrides the env/basename default.
media?: Array<{ // optional. Screenshots, audio, or video for the human to inspect.
mime_type: string, // an image/*, audio/*, or video/* type
data_base64: string, // standard base64 (a `data:<mime>;base64,` prefix is accepted)
filename?: string,
caption?: string
}>
}) => { id: string, status: "pending", expires_at: string, media?: MediaRef[] }
wait_for_answer
Waits for the human to answer, then returns the result. Returns immediately if the ticket is already answered or expired.
wait_for_answer({
id: string,
timeout_seconds?: number // default 60, max 600
}) => {
id: string,
status: "pending" | "answered" | "expired" | "cancelled",
answer?: string,
answered_by?: string, // "human" | "default"
answered_at?: string,
media?: MediaRef[], // the media you attached, echoed back
annotations?: Annotation[] // the human's notes and any rendered markup copy
}
When the human drew on an attached image, the annotated copy is returned as MCP image
content alongside the text, so an agent that only speaks MCP can see the markup without
fetching a URL. annotations[].annotated_media also names a blob under GET /api/media/{id}.
list_pending
Lists the tickets still pending across every agent stream. Takes no arguments.
list_pending({}) => { tickets: Ticket[] }
cancel_ticket
Cancels a ticket the agent no longer needs answered.
cancel_ticket({ id: string }) => { id: string, status: "cancelled" }
The HUMAN ANSWER: prefix
A delivered human answer is prefixed with HUMAN ANSWER: so a model can never confuse it with
its own earlier guess. An answer that came from default_answer gets a clearly different
prefix — DEFAULT ANSWER (applied on expiry; no human responded): — because labelling the
agent's own default as a human answer would be worse than no prefix at all.
Media and annotations
Media is optional: most tickets have none, and a ticket with media is answered exactly like
one without. Attach it with ask_human's media array (up to 8 items, 8 MiB each, 24 MiB per
ticket) when a decision needs a screenshot, a clip, or a recording rather than words.
- Stored out of band. The bytes live in a media store, keyed by an id; the ticket carries
only a
MediaRef(kind, MIME type, filename, caption, size).GET /api/ticketsandtickets.jsontherefore stay small, and the page fetches a blob only when you expand a card. - Served same-origin.
GET /api/media/{id}returns the bytes under the same Bearer auth as every other/api/*route. Nothing is fetched from an external origin. - Expand and inspect. Each attachment is collapsed behind a Show N attachments toggle.
Images open on a drawing canvas (
Box,Draw,Clear markup); audio and video get a player. - Annotate and send back. The human can mark up an image and add notes (notes on audio/video
capture the playhead position). On Answer, a marked-up image is rendered to a PNG, uploaded
with
POST /api/media, and referenced from the answer. Annotations are optional: the human may answer with text, a chosen option, annotations, or any combination — but not nothing. - Back to the agent.
wait_for_answerreturns the annotations as structured fields, and any rendered markup as MCPimagecontent, so the agent sees exactly what the human marked.
The three targets share the behaviour; only the storage differs. FileTicketStore writes blobs
under ${READYROOM_STATE_DIR}/media/, and DurableObjectTicketStore chunks each blob across rows
because a Cloudflare SQLite row is capped at 2 MB.
Three ways aboard
They run the same program. They differ in where it lives and who can reach it.
npx |
Docker from GHCR | Cloudflare Worker | |
|---|---|---|---|
| setup | npx readyroom |
pull ghcr.io/therebelrobot/readyroom |
wrangler deploy |
| runs | on the host, as you | in a container, as a non-root user | on the edge, with no box to patch |
| state | ./.state on disk |
a volume mount | one SQLite Durable Object |
| reachable from | loopback only, by default | loopback; your LAN through a reverse proxy | anywhere, behind Cloudflare Access |
| MCP transport | stdio + Streamable HTTP | stdio + Streamable HTTP | Streamable HTTP |
| live updates | SSE | SSE | polling; the page falls back on its own |
| best for | trying it in a minute | always-on, arm64, survives reboots | agents that cannot reach your house |
npx — one developer, one machine, thirty seconds
npx readyroom
No config, no container, no account. The server speaks stdio MCP (wire it into your MCP client) and also serves Streamable HTTP on the same process for clients that want it.
The singleton. Three MCP clients spawning npx readyroom would otherwise produce three
processes, three attempts to bind port 8971, and three writers to one tickets.json — which
breaks the single-writer invariant and can corrupt the queue. So:
- The first process to start becomes the daemon: it binds the port, owns the store, and
writes
${READYROOM_STATE_DIR}/daemon.jsoncontaining{ pid, port, started_at }. - Every subsequent process becomes a client: it reads
daemon.json, confirms the pid is alive and/healthzanswers, then proxies its MCP tool calls to the daemon overhttp://127.0.0.1:<port>. It serves stdio on its own file descriptors and nothing else. It never writestickets.json.
If daemon.json is stale (pid dead, or the port refuses), the starting process acquires the
daemon role itself and overwrites the file. If the daemon is unreachable but a foreign service
holds the port, the process refuses to start with a message naming the port — it never
silently falls back to a second writer.
Self-hosted Docker on a Raspberry Pi
Always-on, arm64, LAN-reachable, survives reboots. The image is multi-arch
(linux/amd64,linux/arm64); arm64 is required because the deploy target is a Pi.
docker run --rm -d \
-p 127.0.0.1:8971:8971 \
-v "$(pwd)/.state:/app/.state" \
--env-file .env \
ghcr.io/therebelrobot/readyroom:latest
Or as a mergeable compose snippet. It binds to loopback; LAN exposure goes through the reverse proxy.
services:
readyroom:
image: ghcr.io/therebelrobot/readyroom:latest
container_name: readyroom
restart: unless-stopped
stdin_open: true
ports:
- "127.0.0.1:8971:8971"
environment:
READYROOM_TOKEN: ${READYROOM_TOKEN:?set READYROOM_TOKEN}
READYROOM_STATE_DIR: /app/.state
READYROOM_BIND: 0.0.0.0
volumes:
- ./readyroom-state:/app/.state
Copy this file to get a runnable setup without retyping it:
examples/docker-compose.yml — set READYROOM_TOKEN, then
docker compose up -d.
The container runs the same Node entry as npx, in stdio-plus-HTTP mode, as a non-root user, and
handles SIGTERM.
[!NOTE] GHCR packages start private. After the first publish run, flip the package to public in the GitHub package settings, or
docker pullwill fail with an authentication error.
Cloudflare Worker
Always-on, reachable from anywhere, no box to patch. The Worker serves the readyroom page and the Streamable HTTP MCP endpoint from the same origin, backed by one SQLite Durable Object instance.
# 1. Supply the token as a secret (never committed).
wrangler secret put READYROOM_TOKEN
# 2. Deploy.
npm run deploy:worker
The MCP endpoint is per-agent: POST /mcp/{stream}. Each agent gets its own URL, configured
once in the client. There is no cwd on Workers, so basename(cwd) cannot be the fallback —
the stream is required and comes from the path segment or an explicit stream tool argument.
If neither is present, the tool call fails with an error naming both ways to supply it. No
default is invented.
MCP Configuration
An MCP client reaches readyroom over one of two transports. How you run the server decides which one is available.
Entry points
| Command | Target | Transports | State |
|---|---|---|---|
npx readyroom |
Node, on the host | stdio + Streamable HTTP | ./.state on disk |
npm start (node dist/server.mjs) |
Node, built bundle | stdio + Streamable HTTP | ./.state on disk |
npm run dev (tsx watch --import ./scripts/html-loader-register.mjs src/index.ts) |
Node, development | stdio + Streamable HTTP | ./.state on disk |
docker run … ghcr.io/therebelrobot/readyroom:latest |
Docker | stdio + Streamable HTTP | volume mount |
npm run dev:worker (wrangler dev) |
Cloudflare Worker, local | Streamable HTTP only | Durable Object |
npm run deploy:worker (wrangler deploy) |
Cloudflare Worker, edge | Streamable HTTP only | Durable Object |
On the Node targets a process resolves into a daemon or a client (see the singleton): the first process becomes the daemon and serves both transports on the port; later processes join as clients and serve stdio only, proxying their tool calls to the daemon. The role is decided at start — there is nothing to configure.
Transports
- stdio — Node targets only. The MCP client spawns the process and speaks the protocol over
its file descriptors. The server writes nothing to stdout but MCP frames; all logs go to
stderr. Select it by configuring the client to run a
command. - Streamable HTTP — every target. On Node the daemon mounts it at
POST /mcp(methodsGET,POST,DELETE) on the same port. On the Worker it is the only transport, mounted at/mcp(stream supplied as the/mcp/{stream}path segment). Select it by pointing the client at the URL.
The two are not exclusive on Node: one daemon serves stdio and HTTP at once, so one agent can run over stdio and another over HTTP against the same queue.
The /mcp endpoint is Origin-guarded
Both HTTP mounts reject a request whose Origin header is missing or not on the allowlist,
with 403. On Node the allowlist is built from the server's own origins — http://127.0.0.1:<port>
and http://localhost:<port> — plus any READYROOM_ALLOWED_ORIGINS entries. On the Worker it
is the Worker's own origin plus the same extras. See src/security.ts.
[!NOTE] An HTTP MCP client must send an
Originheader that matches the allowlist. A client that sends noOriginat all is rejected. If your client sends a different origin (or none), add it toREADYROOM_ALLOWED_ORIGINS.
Streams over HTTP
On Node the stream defaults to READYROOM_STREAM, else basename(cwd), and can be overridden
per call with the stream tool argument. On the Worker there is no cwd: the stream comes from
the POST /mcp/{stream} path segment, or an explicit stream argument. If neither is present,
the call fails with an error naming both ways to supply it.
Configuration options
All six are read from the process environment on the Node targets, and, on the Worker, only
READYROOM_TOKEN and READYROOM_ALLOWED_ORIGINS are read from [vars] / secrets in
wrangler.toml. src/config.ts is the single source of truth.
| Variable | Default | Required? | Meaning |
|---|---|---|---|
READYROOM_STREAM |
basename(cwd) |
optional | Default stream for tickets. Overridable per call via the stream tool argument. Not applicable on the Worker. |
READYROOM_TOKEN |
(unset) | mandatory on Docker and the Worker, optional on Node | Shared secret for /api/* and the Node /internal/tool-call proxy. |
READYROOM_BIND |
127.0.0.1 |
optional | Bind address. A non-loopback value refuses to start unless READYROOM_TOKEN is set. Not applicable on the Worker. |
READYROOM_STATE_DIR |
./.state |
optional | Directory holding tickets.json, audit.jsonl, and daemon.json. Not applicable on the Worker. |
READYROOM_PORT |
8971 |
optional | TCP port. Must not collide with 3000-3899, which a worktree helper allocates. Not applicable on the Worker. |
READYROOM_ALLOWED_ORIGINS |
(unset) | optional | Comma-separated extra origins allowed on the /mcp Origin guard, appended to the server's own origin. |
The per-target Worker mapping is in Environment variables.
MCP client configuration
stdio (Claude Desktop and other MCP clients)
{
"mcpServers": {
"readyroom": {
"command": "npx",
"args": ["-y", "readyroom"],
"env": {
"READYROOM_STREAM": "my-agent",
"READYROOM_STATE_DIR": "/home/you/.readyroom"
}
}
}
}
Every client that spawns readyroom becomes the daemon or a client automatically; you do not set
the role. Give each agent its own stream with READYROOM_STREAM (or the stream argument to
ask_human). If any process in a shared daemon group sets READYROOM_TOKEN, every process in
that group must set the same value — the client forwards it to the daemon.
For a built or installed copy, replace command with the absolute path to dist/server.mjs
(or the readyroom binary on PATH).
Streamable HTTP (Node daemon)
{
"mcpServers": {
"readyroom": {
"url": "http://127.0.0.1:8971/mcp",
"headers": {
"Origin": "http://127.0.0.1:8971"
}
}
}
}
Streamable HTTP (Cloudflare Worker)
The stream is the path segment, so each agent gets its own URL.
{
"mcpServers": {
"readyroom": {
"url": "https://readyroom.example.com/mcp/my-agent",
"headers": {
"Origin": "https://readyroom.example.com"
}
}
}
}
Directing an agent to use readyroom (AGENTS.md)
Paste the block below into your project's AGENTS.md (or CLAUDE.md) so the agent knows
readyroom is available and how to reach it. It goes at the top level of that file, alongside
your other project instructions.
## Asking a human
When you reach a decision you cannot make alone — a choice with real consequences, a
preference only the operator holds, or anything you would otherwise guess at — ask the
operator through the `readyroom` MCP server instead of guessing or blocking.
- `ask_human` — enqueue a question and return immediately. It never waits. Pass `question`
(one sentence), and optionally `options` (2-5 mutually exclusive choices), `context`,
`default_answer`, `timeout_seconds`, `urgency`, and `stream`. It returns
`{ id, status: "pending" }`.
- `wait_for_answer` — block for the human's answer to a ticket you enqueued. Pass the `id`.
It returns immediately if the ticket is already answered or expired; if it is still
pending, continue with independent work and call it again later. Do not poll in a tight loop.
- `list_pending` — list the tickets still pending across every agent stream. Takes no arguments.
- `cancel_ticket` — withdraw a ticket you no longer need answered. Pass the `id`.
A delivered human answer is prefixed with `HUMAN ANSWER:`. An answer applied from
`default_answer` on expiry is prefixed `DEFAULT ANSWER (applied on expiry; no human
responded):` — never treat that as a human answer.
readyroom MCP questions
How do I add readyroom MCP to Claude Code?
Run claude mcp add readyroom -- npx -y readyroom in your terminal. Add --scope user to make it available in every project.
How do I add readyroom MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does the agent block while waiting for a human?
No, the agent enqueues a ticket and returns immediately, allowing it to continue independent work.
How can I run readyroom?
You can run it using npx, Docker, or as a Cloudflare Worker.
What happens if the server restarts?
The queue is preserved because tickets are written atomically to disk or to a Durable Object.