Monitor Protocol

Shared monitors for people and agents: durable observations, independent subscriptions, and delivery into the tools they use.

Read the documentation · Try it in your browser · Quickstart · Package on npm

The idea

A workspace can have people working in Codex, Claude Code, other agent tools, and ordinary terminals. They need to observe the same work while keeping their own place in it.

The Monitor Protocol gives them a shared service. A monitor exists independently of any conversation, records observations with provenance, and lets each participant subscribe with its own durable cursor. HTTP, SSE, and MCP expose the same objects and rules.

Delivery into a live conversation is a separate adapter. Claude Code's Monitor tool can follow a subscription. The Codex terminal bridge in this checkout can notify an existing, human-opened session through its native queue. A client without a supported wake mechanism can pull when its user returns. The workspace and its observations survive the end of any one session.

The same observations can also feed an operator-defined routine: start a script or agent job when work arrives, record its result, then exit. The routine runner design also covers direct CLI invocation by a person, agent, or action, with prompts and context fetched from local or cloud sources. A bounded implementation now lives in Mentu Recipes: pinned local/HTTPS inputs, a fixed execution policy, and a one-shot MP consumer that acknowledges after a durable report. A continuously supervised general routine service remains design work.

Related MCP server: AgentCloud MCP Server

What it does

There are five parts, and each one is small.

• A monitor is a definition: what is watched, how often, and with what authority.

• An observation is one thing the monitor saw. Each one says where it came from, who caused it, and how much it is worth believing.

• A state is the monitor's running summary, computed from its observations. It says out loud what it does not know, instead of filling the gap with a number.

• A subscription is a reader with its own place in the stream, called its cursor. It reads, does the work, and only then acknowledges. A reader that crashes gets the same items again instead of losing them.

• A lease is how two workers avoid doing the same job twice. It expires on its own if the worker holding it stops.

Configuration is not a sixth part. Pausing a monitor, changing its filter or retiring it is recorded as an observation too. Six months later, the question "why did this change?" has an answer.

What makes it more than a queue

A queue moves messages and forgets them. The Monitor Protocol keeps them as evidence.

A machine cannot claim a person's level of certainty. Every observation carries a rating, from src (a person checked it against the source) down to falsified (checked, and found untrue). A program can report what it measured. The top of the ladder needs a person behind the observation. An agent working for you reaches your level by naming you in one field, on_behalf_of, and the record keeps both names: the agent that saw it, and the person it worked for. It can only name the person who owns the monitor, so it cannot borrow anyone else's level. Anything that tries to climb higher is refused, and the refusal is kept as an observation.

An independent audit showed that the first version of this check could be fooled, because it read its answer from the same request it was judging. It is now enforced, and the conformance suite tests it from five different angles.

It does not lie by leaving things out. A confidence with a missing input lists the input as missing. A source that did not answer is reported as not answering, never as zero. The count of waiting items covers only what this reader would actually receive, so it can reach zero.

Try it

The fastest way is the playground: the real engine runs in your browser, and nothing leaves the page.

To run it yourself, you need Node.js 20 or newer. Start a server:

npx @mentu/monitor-protocol serve --port 8130

Then, in use, it is four steps:

# 1. Define what is watched. The reply includes an owner token, shown once. Keep it.
curl -s localhost:8130/mp/v0/monitors \
  -d '{"id":"ci","name":"CI","horizon":"minute","capabilities":["observe"],"visibility":"public","types":["com.example.ci.run"]}'

# 2. A producer records what it saw, using the owner token.
curl -s localhost:8130/mp/v0/monitors/ci/observations -H "Authorization: Bearer $OWNER_TOKEN" \
  -d '{"type":"com.example.ci.run","subject":"build-412","actor":"probe:ci","tier":"measured","origin":"probe","data":{"status":"failed"}}'

# 3. A reader subscribes once, then takes what it has not seen yet.
curl -s localhost:8130/mp/v0/subscriptions -d '{"monitor":"ci","subscriber":"agent:reviewer","capabilities":["observe"]}'
curl -s "localhost:8130/mp/v0/subscriptions/$SUBSCRIPTION/pull" -H "Authorization: Bearer $READER_TOKEN"

# 4. It commits only after handling it. Send the "next" value from the pull reply.
curl -s localhost:8130/mp/v0/subscriptions/$SUBSCRIPTION/ack -H "Authorization: Bearer $READER_TOKEN" -d '{"cursor": 3}'

Reading never moves the cursor. Only an acknowledgement does, and it never moves backwards. The quickstart walks through each reply.

Use it from your workspace

Give each participant its own subscription. Reading or waking one participant does not advance another participant's cursor. Connecting a client over MCP gives it tools; whether it can start a turn from a notification depends on its host.

See Shared terminal peers and event driven routines for both execution modes, component responsibilities, lifetimes, and live-test evidence.

Sessions also need verified tools. The capability admission API checks pinned MCP tools through the actual Codex thread and requires fresh successful calls before admitting work. It does not inherit the Codex app's private tools or credentials. The workspace status view keeps source health, transport, handling, tool readiness and native wake evidence separate. An optional handling expectation flags overdue delivery receipts even while their worker stays alive; it never acknowledges or launches work. The shared harness contract aligns the Claude plugin design, Codex host integration and other providers around the same semantic capability requirements, ticket ownership, recipes and handling receipts. Concrete adapters must pass their own trials.

Native Codex runtime preview

The native Codex integration contains a pinned source patch and build instructions. It adds session-owned monitor_start, monitor_status, monitor_show, monitor_handled, and monitor_stop tools inside Codex. An operator registers each source; disconnecting or unsubscribing its owning frontend cancels the native consumer. Events arriving during a turn stay pending until guarded idle admission.

This requires the rebuilt Codex runtime. It is not activated by installing this npm package, an MCP server, or a skill, and it does not modify an already running Codex conversation.

Codex terminal bridge

The bridge ships in the package from 0.3.0. If the version on npm is older than 0.3.0, build it from this checkout, then run it from the Codex session a person already opened:

npm ci
npm run build
# Set MP_SUBSCRIPTION_TOKEN securely to this participant's existing reader token.
node dist/index.js bridge run --adapter codex \
  --base http://localhost:8130 --subscription <id> \
  --token-env MP_SUBSCRIPTION_TOKEN --state ~/.monitor-protocol/codex-session

The bridge discovers that session, checks its native queue capability, and stops when the session dies or bridge stop is requested. It never opens or resumes a model session. A notification carries a delivery reference and fingerprint. The session reads it with bridge show, handles it under its existing authority, and records a disposition with bridge handled. Only then does the bridge acknowledge the subscription.

The session bridge guide covers commands, supported platforms, receipts, retries, and how to add another provider adapter.

Claude Code and MCP

Add it to Claude Code as an MCP server. It runs its own monitor server, so give it its own state file:

claude mcp add -s user monitor-protocol -- npx -y @mentu/monitor-protocol mcp --state ~/.monitor-protocol/mcp-state.json

Or follow a subscription from a session with the Monitor tool:

Monitor(command: "npx -y @mentu/monitor-protocol watch --base http://localhost:8130 --subscription <id> --token <token> --catch-up")

The watch prints one line per observation and, after each batch, NEXT <cursor>. By default the CLI acknowledges nothing: once the session has handled the batch, it runs monitor-protocol ack --base <url> --subscription <id> --token <token> --cursor <n>. When the Monitor's time runs out, start it again. The subscription remembers the last place the session acknowledged, so an unhandled batch remains eligible for redelivery within the server's retention period. If the server restarts, the watch prints DOWN, waits, and carries on when the server is back. The guide Claude Code and MCP covers both, and the tools.

The watch command also works in an ordinary terminal. Printing or enqueueing a notification is not processing it. Do not use the compatibility option --ack-on-print for a session that still needs to act on the output. Library callers must set ackAfterPrint: false explicitly; its historical default remains true.

Safe by default on your machine

A monitor server usually runs next to a web browser, so it assumes every web page you open can reach it.

• A web page is not you. Requests from a browser page are refused unless you allow that page with --allow-origin. Command line tools are unaffected.

• Nothing reaches it through a borrowed name. On your own machine it only answers to localhost, 127.0.0.1 and ::1, which stops DNS rebinding.

• One request cannot exhaust it. Request bodies over 1 MiB are refused.

• Your state survives a bad day. Each write is flushed to disk before it replaces the last, the previous copy is kept, and a damaged file is set aside instead of overwritten.

• Only one server writes a state file. A second one refuses to start and says which process holds it.

Learn more

• What is the Monitor Protocol?

• Introducing the Monitor Protocol: why we built it, and how it works

• Agents acting for people: the trust rules in plain words

• Concepts and Reference

• The fourteen principles, each one learned from something that went wrong in a running system

What is in this repository

Build your own implementation

Read the principles, implement the five objects over HTTP, and run the conformance suite against your server:

npx @mentu/monitor-protocol conform --base http://127.0.0.1:8124
python3 conformance/python/run.py --base http://127.0.0.1:8124 --subjects a,b,c

The suite covers C01–C34. Run it against the version you intend to deploy. Atrio, an event log, is a second implementation; its published results and limitations are recorded in the implementation guide. Server conformance and the ability to wake a particular session are tested separately.

To use the reference server as a library:

import { MemoryStore, MonitorService, createHttpServer, MonitorClient } from "@mentu/monitor-protocol";
const service = new MonitorService(new MemoryStore("state.json"));

Status

Releases are tagged on GitHub and listed in the changelog. Not every tag reached npm: 0.2.0 and 0.3.0 were tagged but never published there. A release reaches npm only as the tarball that CI built and tested. From 0.3.0, a release includes the session bridge described above. The objects and methods are stable enough to build on. Names such as the ai.mentu prefix may still change before version 1.0. Contributions are welcome: see CONTRIBUTING.md.

License

Apache 2.0.