Run your first XMesh mission

One package gives you xmesh, which runs XMesh, and xmesh-mcp, which lets a coding agent call it.

npm install -g @sym-bot/xmesh

Register XMesh for every project, then start a new Claude Code session. It now has one XMesh tool, mesh_mission.

xmesh mcp install --user

This adds XMesh at Claude Code’s user scope, through claude mcp add; if claude is not on your PATH, it prints the exact command instead. Each session is still recorded under its own seat and its own project. To undo it: claude mcp remove --scope user xmesh.

You don’t need to start XMesh yourself. The first time Claude Code calls the tool, XMesh starts in the background. It finds the claude CLI on your PATH and runs missions through it, on your own Claude account. It saves its passcode in ~/.xmesh/passcode and listens on http://localhost:8787. To start it yourself, run xmesh: from a terminal it starts in the background, says where its log is, and returns. xmesh stop stops it, giving in-flight missions time to finish first. If /api/v1/_/health shows ready:true, grounded:false, XMesh can run work; it just has no mesh peers yet.

Only one project? Run xmesh there instead. It writes that project’s .mcp.json, so the bridge is already wired; Claude Code in that folder asks you to approve the xmesh server once.

cd your-project && xmesh

To hand missions over from Codex, or to wire a directory by hand (missions still run on your Claude login):

codex mcp add xmesh --env XMESH_URL=http://localhost:8787 --env XMESH_SEAT=my-coding-agent -- xmesh-mcp
# or, from any project directory:
xmesh mcp install --url http://localhost:8787

Your seat is who your missions are recorded as asked by. It is derived from the Claude Code session, as claude-<project>-<session>. In a folder set up with sym-mesh-channel start, it is that folder’s mesh node name from .sym/node.json, so confirmations reach that node. Set XMESH_SEAT to use another name; the runtime matches the seat exactly. An identified requester receives mission status and completion confirmations, including through the SYM mesh plugin if you have it. With no seat, missions still run, but the requester is recorded as anonymous and gets no pushed confirmations; the mission reply says so and tells you how to check on it.

Fully restart the coding agent after adding or changing the server. It loads XMesh’s tool only when it connects; restarting XMesh does not refresh it.

In Claude Code, ask for a task in XMesh. You do not need to name an MCP tool or write tool syntax. “This repository” means the project you are in, and results are written there. Say what done means, if you can, in terms a machine can check.

Run this task in XMesh: review this repository and identify the top three release risks.

Claude Code calls mesh_mission and returns the mission id. The deliverable is written into your project; the critic’s verdict arrives separately.

What comes back. If your ask states what done means (a file that must exist, what it must say), XMesh tests that itself; without it, a person validates the result. Independent review is on by default for work, review, research and assessment missions. A critic reviews a completion it did not author. It reviews skeptically: your criteria come before how the doer framed the work. Its verdict is recorded beside the result: verified, objected, or absent if none arrived in time. /api/v1/_/health reports the verification state. A critic that cannot run leaves the mission unreviewed, never passed.

Other kinds of mission are asked the same way. For a second opinion on one file or saved diff, ask for a review; the target is a path relative to your project, or absolute on the machine running XMesh. Make it a habit: before you tell anyone a change is done, ask XMesh to review it.

Ask XMesh to review docs/store-design.md: can its tests catch what they claim to?

mesh_mission {
  action: "create", kind: "review",
  focus:  "Can this design's tests catch what they claim to?",
  spec:   { target: "docs/store-design.md" }
}

For a cited answer rather than a deliverable, ask a question (kind question). Every claim in the answer names the agent and record it came from; if nothing recorded supports an answer, it says so. Claude Code waits up to 90 seconds for it by default.

Follow a mission by its id, however long ago it ran:

mesh_mission { action: "read", id: "<mission id>" }                       # its result, checks and review
mesh_mission { action: "read", id: "<mission id>", part: "root-cause" }   # why it stopped
mesh_mission { action: "list", status: "blocked" }                        # your missions, by status
mesh_mission { action: "operate", id: "<mission id>", op: { op: "verdict", verdict: "validated" } }

The last line records your own ruling (validated or dismissed) beside the mission’s status. You can also just ask Claude Code in words, for example “check on that XMesh mission”.

Settings are kept with xmesh set and apply at the next start, xmesh restart. xmesh settings lists every setting, its value and where it comes from; xmesh unset <key> returns one to its default.

Codex instead of Claude: xmesh set provider cli:codex. Missions then think with Codex. On Windows, Codex answers but cannot be a mission’s worker or critic: its sandbox there refuses every command, so XMesh refuses it before anything starts. Work and review on Windows need Claude.

A second model for the critic is a setting, not the default. Left alone, the critic runs on the doer’s own CLI and model. To put the critic on a second model for every mission:

xmesh set critic.mind codex       # another vendor's CLI, not on Windows: the strongest separation
xmesh set critic.model <model>    # another model from the same vendor
xmesh restart

A room’s policy (criticMind, criticModel, set with the call in step 6) overrides these for missions filed from that room. A mission asked from Claude Code names no room, so the settings above are what reach it. The critic never falls back to another model: if the one you name cannot run, the mission reads unreviewed, never passed.

Review off: to save usage, xmesh set critic off. Missions then read unreviewed.

An environment variable still wins for one start: XMESH_MISSION_MIND_B, XMESH_MISSION_MODEL_B, XMESH_MISSION_CRITIC=0 or XMESH_LLM_PROVIDER in front of xmesh. In PowerShell, set it first: $env:XMESH_MISSION_CRITIC = "0"; xmesh.

A fresh install runs under a default cap of 40 work units per UTC day. One work unit is one commissioned mission XMesh accepts, not one model call. Until someone chooses a limit, /api/v1/_/health reports chosen: false, and a mission refused at the cap gets a 402 that says so and shows what your day actually cost.

Only a person can change the limit: the mesh never sets its own budget, and unbounded spend is never a default. Open a session with the passcode, then record your choice once:

curl -s http://localhost:8787/api/v1/_/session \
  -H 'content-type: application/json' \
  -d '{"credential":"YOUR_PASSCODE","seat":"developer"}'

# Copy the token from that response:
curl -s http://localhost:8787/api/v1/_/spend/choice \
  -H 'content-type: application/json' \
  -H 'x-mesh-token: YOUR_TOKEN' \
  -d '{"mode":"workload","dailyUnits":40}'

For a daily USD limit, send {"mode":"usd","dailyUsd":20} instead; to accept unbounded spend explicitly, {"mode":"unbounded"}. Every choice is recorded against your name.

Seeing another 402? There are two, and they are unrelated: the spend cap above, and the licence 402 on Enterprise Federation endpoints, which refuses reads across organizations without a production Team Mesh licence. Neither means your setup is wrong.

Save a lane (a saved model connection) and point a room at it. This example uses OpenAI; any endpoint that speaks the OpenAI or Anthropic API works.

Put the key in a file. XMesh hands it only to the mind it starts, never to its own environment.

umask 077; mkdir -p ~/.xmesh/secrets
printf '%s' 'sk-…' > ~/.xmesh/secrets/openai.key

Get a session token with the passcode, then save the lane. protocol is the API the endpoint speaks. XMesh asks the provider whether it serves the model you named and records the answer; Station’s Models panel shows it too.

TOKEN=$(curl -s -X POST localhost:8787/api/v1/_/session -H 'content-type: application/json' \
  -d '{"credential":"<passcode>","seat":"me"}' | jq -r .token)

curl -s -X PUT localhost:8787/api/v1/_/lanes/openai -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"protocol":"openai","transport":"api","baseUrl":"https://api.openai.com/v1",
       "keyFile":"/Users/you/.xmesh/secrets/openai.key",
       "model":"gpt-4o-mini","pool":"openai","capabilities":["text","code"]}'

Point a room at the lane, then file a mission from that room.

curl -s -X PUT localhost:8787/api/v1/_/rooms/my-room/policy -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{"doerMind":"openai","doerModel":"gpt-4o-mini"}'

curl -s -X POST localhost:8787/api/v1/mission -H "Authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' -d '{
    "kind": "work",
    "cat7": {
      "focus": "In your current working directory, write the file openai-proof.md with exactly two lines: line 1 \"lane: openai\"; line 2 \"sum: \" followed by the sum of the integers from 1 to 100. Do nothing else.",
      "commitment": "CHECK: file openai-proof.md\nCHECK: contains openai-proof.md sum: 5050\nCHECK: contains openai-proof.md lane: openai"
    },
    "spec": { "originRoom": "my-room" }
  }'

To confirm which model ran, check XMesh’s record, not the model’s own account: the mission record lists each worker’s mind and model, and your provider’s usage page shows the calls on that key. A Codex doer writes only inside its mission workspace, so use relative file names. Keep the MCP bridge on the same version as XMesh: an older bridge drops the origin room, and the mission then runs on the default mind.