* mcp: free memory and disk in the status line
* mcp: free memory and disk in the end line of answers
* mcp: ❗️ after a low part of the end line, RAM below 5%
53 KiB
Testing @simplex-chat/mcp v0.3
Node.js 22. Claude Code runs on the same computer as serve: the server listens on 127.0.0.1 only.
Build
Here
All commands run in /code/simplex-chat-6/packages/simplex-chat-mcp. The dependencies are installed by npm install; simplex-chat comes from npm and downloads libsimplex and its Node.js add-on to ~/.cache/simplex-chat at the first start.
node node_modules/typescript/bin/tsc
node node_modules/jest/bin/jest.js test/unit # about 10 s
SMP_SERVER=/code/steward/node_modules/.cache/smp-server/smp-server-v7.1.0-beta.3 XFTP_SERVER=/code/simplexmq-5/dist-newstyle/build/x86_64-linux/ghc-9.6.3/simplexmq-7.1.0.9/x/xftp-server/build/xftp-server/xftp-server node node_modules/jest/bin/jest.js test/e2e # about 4 minutes; a local smp-server and xftp-server on free ports
node_modules is not writable here, so the end-to-end test takes the smp-server and xftp-server binaries from SMP_SERVER and XFTP_SERVER instead of downloading them to node_modules/.cache.
On your own machine
- Check out simplex-chat master; the package is
packages/simplex-chat-mcp. - In that folder:
npm ci, thennpx tsc.tscleaves the output of deleted sources indist.npm packandnpm publishdeletedistand build it again (scriptprepack). They bundle the production packages ofnode_modules(bundleDependencies), without a lockfile. Runnpm cibefore a pack, so that the tree ofpackage-lock.jsonis innode_modules, as in the publication bybuild.yml. node dist/cli.js serve my-agent --display-name "My Agent". At the first start,simplex-chatdownloads libsimplex and its Node.js add-on, with aDownloading ...line each on stderr.- Tests:
npx jest test/unit;npx jest test/e2edownloads smp-server and xftp-server v7.1.0-beta.3 on Linux, and elsewhere takesSMP_SERVER=/path/to/smp-server XFTP_SERVER=/path/to/xftp-server.
Until the package is published, the printed hint npx -y @simplex-chat/mcp register my-agent stands for node dist/cli.js register my-agent.
The tests of 0.2
serve keeps the behaviour of 0.2, except the reply_to of a message: it has the quoted message's sender, type and text, and is present also without an ID. The 274 unit tests of 0.2 and its 13 end-to-end tests in scenarios and mcp, from commit be668564d, pass unchanged on this source, except one expectation: reply_to in the unit test "describes a group message" is now {chat: "#15", item: 30, text: ""}. They run in a copy of the package with the test folder of 0.2. Run these commands from the repository's root, with SMP_SERVER and XFTP_SERVER set as above:
mkdir -p /tmp/v02
git archive HEAD packages/simplex-chat-mcp | tar -x -C /tmp/v02
rm -rf /tmp/v02/packages/simplex-chat-mcp/test
git archive be668564d packages/simplex-chat-mcp/test | tar -x -C /tmp/v02
ln -s "$PWD/packages/simplex-chat-mcp/node_modules" /tmp/v02/packages/simplex-chat-mcp/node_modules
cd /tmp/v02/packages/simplex-chat-mcp
node node_modules/jest/bin/jest.js test/unit test/e2e/scenarios.test.ts test/e2e/mcp.test.ts
Start, join, register
node dist/cli.js serve my-agent --display-name "My Agent". NAME, heremy-agent, names the data folder and the Claude Code entry;--display-nameis the name people see in SimpleX. It prints the data folder (~/.simplex-mcp/my-agent), creates the agent control chat "My Agent", and prints a QR code and a link that works once. For a short link the QR code has 33 modules and takes 37 columns × 19 lines;--qr-code largeprints it at 74 × 37. Keep it running; Ctrl-C stops it.node dist/cli.js --helplists the options.- In the SimpleX app, scan the QR code, or paste the link into "Connect via link". If the code does not scan, restart with
--qr-code large. The chat "My Agent" appears withI'm your agent. I ask here before I connect, send, download a file or leave a chat.The terminal printsAlice joined (member N) and is now an owner. The link is deleted.and the register hint. node dist/cli.js register my-agent. It printsAdded to Claude Code: scope user, server simplex-my-agent.Run it in a terminal with the sameCLAUDE_CONFIG_DIRas the one whereclauderuns:claude mcp add-jsonwrites to the config of its own environment.- Add
"mcp__simplex-my-agent"topermissions.allowin~/.claude/settings.json, so Claude Code does not prompt for each call; approval happens in the SimpleX app. - Start
claude./mcpshowssimplex-my-agentconnected with 6 tools. A session started beforeregisterdoes not load the entry; start a new one.
Try the tools
Prompts for Claude Code, one at a time. A call that waits more than 2 minutes, for example for an approval, moves to a background task, and its result arrives as a notification.
By name, first:
Connect to @directory.simplex as yourself.While the name is not registered: the tool errorName not found: This SimpleX name is not registered. Please check the name., and no card. Once it is registered: the cardI want to connect to bot SimpleX Directory (@directory.simplex), as myself.; after the approval, step 1 below returnsstatus: known, with no card.
The directory by its address (docs/DIRECTORY.md):
Connect to the SimpleX Directory as yourself at https://smp4.simplex.im/a#lXUjJW5vHYQzoLYgmi8GbxkGP41_kjefFvBrdwg-0Ok and tell me which commands it advertises.Card:I want to connect to bot SimpleX Directory, as myself.Tap/approve 1. The card becomesI connected to ...withApproved by Alice.; Claude getsstatus: done, the chat@N,commandsand the welcome message.Search the directory for hiking groups.Card:I want to send a message to bot SimpleX Directory:with the text. Approve it; Claude gets the bot's answers inresponses.Send /help to the directory.A bot command is sent as text.Check for new messages from the directory, waiting up to 60 seconds.receivewithwait.List your chats and pending actions.list.- Reject one card with its
/reject @N A: the call returnsstatus: rejected; the card ends withRejected by Alice./pendinglists the waiting cards.
Approval of all messages to a chat, and leaving:
Search the directory for Monero groups.On the card, tap/approve @N all. The reply isApproved for bot SimpleX Directory (@N) by Alice. /revoke @N, and the search is sent.Send /help to the directory.It is sent without a card; the agent control chat then getsI sent a message to bot SimpleX Directory:,`/help`andApproved for this chat by Alice. /revoke @N.listshowsapproved: truefor the directory.- Tap
/listin the command menu: one line per chat; the directory's line ends with, approved for this chat by Alice. - Tap
/revoke @N:Messages to bot SimpleX Directory (@N) need approval again.The next send gets a card. Leave the directory.Card:I want to delete bot SimpleX Directory (@N).Approve it: the call returnsstatus: done, andlistno longer shows the directory.- Join a group from the search results, then
Leave that group.Card:I want to leave group <name> (#N).Approve it: the members see that the agent left.
A channel:
Search the directory for channels about trail running.Take a channel link from the answers.Connect to <the channel link> as yourself.Card:I want to connect to channel <name>, as myself.Approve it; Claude getstype: channel,role: observerand the recent posts inmessages.Wait up to 10 minutes for a new post in that channel.receivewithwaitreturns the next post.
Files, in a group of yours:
- In the app, create a group and copy its link.
Connect to <the group link> as yourself.Approve the card. - Send a photo to the group from the app.
Check for new messages in that group.The message hasfilewithtype: imageandstatus: offered. Download that photo.Card:I want to download a file from Alice in group <name> (#N):, with the photo's preview, the file name, its size, andServers: known.when the app uploaded it to servers the agent also has. For a large video asked for right after sending it, the call waits until the upload finishes, and only then the card appears.- Tap
/forward #N A: the photo arrives in the agent control chat, as a reply to the card when its preview and the card fit in one message, and the card stays pending;~/.simplex-mcp/my-agent/files/group-N/has no file, and the photo is in~/.simplex-mcp/my-agent/forwarded/group-N/. - Tap
/receive #N A: the call returnsstatus: doneand the path,~/.simplex-mcp/my-agent/files/group-N/<file ID>.jpg. - Send a document,
Download that file., and tap/receive #N A allon its card: the reply isFiles approved for group <name> (#N) by Alice. /receive #N off, and the download completes. The next file downloads with no card;/listshows, files approved by Alice. Tap/receive #N off. - Send another file,
Download it., and tap/reject #N A: the call returnsstatus: rejected. Send the photo /home/alice/trail.jpg to that group, with the text "trail map".Card:I want to send a message to group <name>:,`trail map`andattaching image `/home/alice/trail.jpg`, SIZE, with the photo's preview. Approve it: the group gets the photo, resized to at most 261120 bytes, with its preview.Send ~/.ssh/id_ed25519 to that group.The call returns the errorfile: /home/alice/.ssh/id_ed25519 is refused: ..., and the agent control chat getsRefused to send `/home/alice/.ssh/id_ed25519` to group <name> (#N): .... A symbolic link to the key gets the same refusal, with the key's real path.- With
ffmpeginstalled,Send /home/alice/ride.mp4 to that group.: the card and the message show the video's first frame and its duration; withoutffmpeg, a gray preview and duration 0. - Tap
/leave #N: after the reply, the agent postsFiles from group <name> (#N) are kept in `~/.simplex-mcp/my-agent/files/group-N`: K files, SIZE. /delete #N files. Tap/delete #N files:Deleted K files from #N, SIZE.; again:No files from #N.
Incognito, as a second agent, because the first one already knows the directory:
node dist/cli.js serve scout --display-name "Scout" --port 5227; join its control chat "Scout" with the printed link;node dist/cli.js register scout; add"mcp__simplex-scout"topermissions.allow;/mcp reconnect all.Using simplex-scout, connect to the directory incognito: https://smp4.simplex.im/a#lXUjJW5vHYQzoLYgmi8GbxkGP41_kjefFvBrdwg-0OkCard:I want to connect to bot SimpleX Directory, incognito.Approve it; Claude getsknown_as, a random name.Using simplex-scout, list your chats.The directory hasincognito: trueand the sameknown_as. A send card for it sayswhere I am incognito.
Stop and restart:
- Stop the server while a card waits: the terminal prints
Stopping: sending 1 cancelled card, up to 10 s. Ctrl-C to stop now., and the card ends withCancelled: the server stopped.A second Ctrl-C during the wait stops the server at once. With no card waiting, Ctrl-C stops it at once. After a restart,/approveof that number repliesAction N is not pending., and the next card has the next number. - A second
serve my-agenton the same data folder exits withAnother server uses ... (PID N). If no server runs, remove .../lock.A port in use exits withPort 5226 is in use. Start with --port N., before any link is printed. - Restart with
--new-token, withoutregister: after the reconnection,listreturns the chats. Checked withclaude -pand an--mcp-configentry withheadersHelper, Claude Code 2.1.302, 2026-10-18.
Claude Code checks
- C2, protocol: passed with Claude Code 2.1.302 in the default runtime, with
MCP_PROTOCOL_NEGOTIATION=legacyand withMCP_SDK_GENERATION=v1. To repeat it, writec2.jsonwith{"mcpServers": {"simplex-my-agent": {"type": "http", "url": "http://127.0.0.1:5226/mcp", "headersHelper": "cat <your home folder>/.simplex-mcp/my-agent/headers.json"}}}, and run it once as is and once with each variable before it:Each run shows the chats, with the preset contact "Ask SimpleX Team".claude -p "Call the list tool and show its result." --strict-mcp-config --mcp-config c2.json --allowedTools mcp__simplex-my-agent - C3, subagent:
Use a subagent to send "trail shoes" to the directory.While the card waits, the subagent's call stays in the foreground, with no background task; it returns after/approve. - C4, reconnect: restart
serve my-agent; in the running session,/mcp reconnect all;listreturns the chats. - C5, register again:
node dist/cli.js register my-agentprintsAdded to Claude Code: scope user, server simplex-my-agent.;claude mcp listshows onesimplex-my-agent. - C6, Esc: ask for a send, and press Esc while its card waits;
List your pending actions.shows the action withopen: false; the same request again attaches to it, and/approvereturns the result to that call. - Host mode: restart with
node dist/cli.js serve my-agent --approve host, then/mcp reconnect all.Send /help to the directory.makes Claude Code prompt, despite the allow rule; so doesleave. After you allow it, the agent control chat getsI sent a message to bot SimpleX Directory:,`/help`andPerformed without approval (mode host).Aconnectto a link not yet joined gets the same prompt and an outcome card; a target already joined returnsstatus: known, with no card.
Claude Code plugin
Install the plugin before it is published
The MCP server and the SessionStart, UserPromptSubmit, Stop, PostModelSwitch, PostToolUse, PostToolUseFailure and PostCompact hooks, and the PreToolUse hook of every tool, run node ${CLAUDE_PLUGIN_ROOT}/dist/cli.js. The PreToolUse hook of the plugin's tools also runs node ${CLAUDE_PLUGIN_ROOT}/plugin/allow.js, and the MessageDisplay hook runs node ${CLAUDE_PLUGIN_ROOT}/dist/display.js. Their modules are bundled in the package. Claude Code 2.1.322 installs a plugin's dependencies only when the plugin's folder has bun.lock, npm-shrinkwrap.json, package-lock.json or bun.lockb. The package has none of them, so Claude Code installs nothing. In step 1, a packed build is laid out in the same way. test/e2e/launch.test.ts checks that layout.
-
In
packages/simplex-chat-mcp, install the tree ofpackage-lock.json, pack the build, and unpack it into a new, empty folder:npm ci npm pack --pack-destination /tmp mkdir /tmp/simplex-plugin tar -xzf /tmp/simplex-chat-mcp-0.3.0.tgz -C /tmp/simplex-plugin --strip-components 1 -
Start Claude Code in any project folder, with the plugin and its channel, and with its own data folder:
SIMPLEX_MCP_HOME=/tmp/simplex-mcp-test claude --plugin-dir /tmp/simplex-plugin --dangerously-load-development-channels plugin:simplex@inline--plugin-dirloads the plugin for that session only, assimplex@inline. -
After a change in
src/, delete/tmp/simplex-pluginand repeat step 1. Then stop the service, because a new service of the same version doesn't replace it:kill $(cat /tmp/simplex-mcp-test/service.lock).
Automated tests
-
npm testruns the unit tests of the plugin's parts:- the session server and its channel;
- the service;
- the hub with its Main group, the sessions' groups and the tool-use cards;
- the hooks, the display hook included;
- the plugin files.
In these tests, the Stop hook reads the model of its answer from the end of a sparse 3 GiB transcript. It finds the model even when the answer's entry is written after the hook started. The UserPromptSubmit hook marks a prompt as typed only when its record has the origin
human. Task notifications, messages of other sessions and channel prompts are not marked. A typed prompt is marked also when the transcript is created with its entry 30 reads after the hook started, as after a user's own prompt hook of 3 s. The hook sends the one-line note of each kind of Claude Code's own prompt, a teammate's message included, also when idle notifications precede it in its prompt, and none for a typed or a channel prompt or idle notifications only. A note stays on one line when the sender's name has a line break or a control character. A prompt that reaches a running turn is found by its queued command or its own later entry, and it is marked mid-turn, also when the turn's first entry is out of the tail and only its tool results are in it. Its record is taken by its text, past a meta entry with the same prompt ID; a prompt with the text of the turn's own prompt waits while it is queued. A typed prompt still queued after the reads is typed and mid-turn. The hook sends the note of Claude Code's own prompt also when a later prompt with its text is still queued after the reads, as a repeated monitor event. The hub posts the note as Claude, without a quote. A mid-turn prompt ends no tool-use card and keeps the turn's quote; an owner's prompt added to the turn adds a turn record, and the answer quotes it. An answer without a turn record quotes a prompt pushed since the latest answer, and never an older one that no prompt hook matched. A member's emoji reaction reaches the session as the emoji after the quote line of the reacted message, with that message's ID asitemandreplyTo.item. A reacted image or video without a caption is quoted with its type and file name, and its file is not received. One of the apps' eight emoji reaches the session. Another reaction, such as U+FE0F alone,❤️with U+FE0F, a newer emoji, a text of two lines or another type, reaches no session and gets the replyThis reaction is not supported.The reply is posted once for each member and reacted message, also when the member removes the reaction and adds it again, and never for a reaction to the reply. The reactions of an observer and ofUser, removed reactions and reactions in the Main group, with one of the eight emoji or another value, reach no session and get no reply. A reaction to a pending tool-use card leaves the card pending. The opening message of a reaction's turn, which the answer fills, quotes the reacted message, Claude's own answer included, and two equal reactions to one message are quoted in their own turns. The tool hooks send a step at the start of each tool use of the main conversation, with its text from the tool's input and paths relative to the session's folder, and at its end with ✅, ❌ or ⏹️ and the duration, or with(in background)for a launch in the background; Grep and Glob show the pattern, then the path; a tool use of a subagent or of this plugin, or without its ID or tool, sends nothing. The hub posts the start of a step as a silent live line, updates it at the step's end with live off, also while the start's send is in flight, and posts an end that arrives before its start as a silent line, and nothing for that start. Steps without an end are completed with their own text at an answer, at a prompt that starts a turn, at the last detach and at the hub's stop, not at a prompt added to the running turn, and the hub posts nothing for their later ends. A line still live 23 hours after its start is completed with its text, and the later end is posted as a new silent line. When the wall clock moves 23 hours on while the timers stand still, as in a sleep, the line is completed at the next check of the minute or at its step's end. The hub's stop waits for the updates that the last detach started. A refused step gets one refusal post,Claude's note was not posted: ..., as a refused note does; a failed send or update is logged, and nothing more is posted. A prompt that starts a turn gets an empty silent live message afterUser's post, as a reply to an owner's prompt, and none for a prompt added to the running turn, a command or Claude Code's own prompt. The turn's first text, step or answer fills it, only from a hook that started no earlier than the prompt's, and an opening message that nothing fills gets⏹️ Stopped. A text that arrives whileUserposts the prompt waits for the opening message and fills it afterUser's post. When the update of the opening message fails, as after its deletion, the turn's text, step and answer are sent as new messages, and the opening message gets⏹️ Stoppedwhen that update succeeds after a transient failure, and a text that was never posted does not stand for the answer at Stop. A live text and an opening message are completed 23 hours after their send by the wall clock, a text in the opening message counted from the opening message's send. The display hook posts each batch with the session, the process and the batch, returns at once when no service runs and starts none, gives up after 1 s when the service does not answer, and loads only Node modules,paths.tsandservice-request.ts. The hub streams each text into a silent live message from its first line that is not blank, in index order, updates it at most every 3 s, shows it whole and live at its final batch, and finalizes it 10 s later, at Claude's next step, or at Stop with the end line. A text that outgrows a message continues in a new live message, for Latin, Cyrillic and CJK texts. At Stop, the streamed answer is completed with the Stop hook's text when it differs, and the answer is posted only when no text of Claude starts it. A note, a text and every part of an answer but the last are silent. The answer's last message ends with the end line,!- Done in DURATION!, and gets priority 1, in its send or in the update that adds the line; a last part with no room for the line is split so that both parts fit. The quote line of a reply or a reaction to Claude's answer leaves out its end line, and keeps such a line of a member's message. A refused answer gets the end line at the end of its refusal. A blank answer fills the opening message with the end line. The hub drops the later batches of an ended text and the first batch of a text whose hook started before the last answer. Live texts are finalized with their text at a prompt that starts a turn, at the last detach and at the hub's stop. A refused text gets one refusal post,Claude's text was not posted: ..., and its message keeps the text accepted last. A refused answer, streamed or not, gets one refusal, in the turn's opening message when the refused post would fill it, and the answer is not posted again. A refused step that would fill the opening message fills it with its refusal. When that update with the refusal fails too, the opening message gets⏹️ Stopped, and nothing more is posted. A refused text posts nothing more, also when it outgrows a message or when an update was scheduled before its end. A long answer whose later part is refused keeps its first part in the opening message./approve N allon a tool-use card approves the use and its tool for the rest of the session, replies with/revoke TOOL, and sends the approved tools to the session; a later card of that tool says that Claude Code still asks for it and offers noall. An approved tool counts only while its approver is an admin or owner, after a role change and after/observer, and no more after the approver leaves or is removed./revoke TOOLends the approval,/listshows the approved tools after the chats, and/approve N allof another kind of action is refused. The approvals are kept across a detach, and each new attachment gets them. The service keeps them when the session's process registers and attaches again, and ends them when another process registers the session and when the session closes. A process with the PID of an ended process of the session and another start time counts as another process, and so does each registration of a process whose start time is unknown. The start time of a running process reads the same twice and differs from that of a later child; a process that does not run and an ID that is not a positive integer have none. While two processes have the session attached, only the attachments of the process that registered it last get the approved tools, and the others get an empty list. The tool approvals end, and the session gets an empty list, when the session's group is lost: deleted, Claude removed, or Claude no longer its owner, at an event and at a load. The session server answers the PreToolUse hook withallowfor a tool approved on its current attachment, and with an empty text for other tools, after its attachment ends, and in a run that is not interactive. The PostCompact hook sends the line of a compaction with its trigger and token counts, also when the boundary is written 30 reads after the hook started. It sends nothing for an input withagent_id, for a subagent's boundary, for a boundary older than 60 s and for one stamped more than 5 s after the hook started. The SessionStart hook of a compaction sends no model. The list of sessions is posted silent in the Main group after the greeting, only while the group has an owner, and edited only when its text changes: a running session's line follows Claude Code's record,busy,waiting,idleorshell, and its cards; a record being written keeps the last state; a missing record or another status showsrunning; a tool-use card counts only while the record sayswaitingor is unknown, also with an unknown status, and a card cancelled by a stop never; the stop's edit comes before the wait for the cancelled cards. A FIFO as the record showsrunning, and a read that stalls keeps the last state, ends the render within a second and is not repeated while it stalls. A new list whose item can't be saved is deleted and posted again at the next render, and a text refused as too large is not sent again until it changes. The other sessions share the last line, newest first; with 400 sessions of 50 four-byte characters, it keeps the names that fit one message and counts the rest, also with the quote of/sessions, and at least 62 lines of running sessions fit. A list 23 hours old, or whose edit is refused, is replaced and the old one deleted for everyone; a refused deletion is logged. A new service edits the list kept in the Main group's data, and the new Main group of a reset gets a new list once an owner joins. The session server sends the absolute path of Claude Code's record, fromCLAUDE_CONFIG_DIR, also a relative one, or~/.claude, and the service passes it to the session. The Stop hook sends the usage of its turn: the time from the turn's first prompt entry to the answer, the output tokens of its distinct responses without earlier turns and subagents, and the context of the answer's response,2 min 13 s · 1.6K output tokens · 535K tokens in context. It finds the prompt entry also when it is more than 1 MiB back, and sends no usage past 64 MiB, without a prompt ID or for a synthetic answer. The PostModelSwitch hook marks its model as a switch. The end line shows the usage in place of the duration, and the plan's usage of the newest status line report,· 5 h: 34% · week: 61%, without a window whose reset time has passed and without an older report that arrives later. It ends with the free memory and disk that the hub reads at each answer,· RAM 12 GB free · disk 3.4 GB free❗️, each with ❗️ after it when low, inside the one small-print span, and without the disk part when it is unknown; the hub reads them from its own data folder. The hub postsModel changed to MODELfor a switch andEffort changed to LEVELfor a change of a known level, also from the status line, as silent small lines before the other posts of the request, and none for a first value, a model of an answer or an older value. Once the status line reports, the hub takes the effort level only from it, so a hook's level of one turn, as afterultrathink, posts no line and changes no description. An answer's model without[1m]keeps the shown model with it. The status line command prints the model, the effort level, the context, the plan's usage and the free memory and disk,RAM 12 GB free · disk 7.3 GB free, in TB, GB with one decimal below 10, or MB, rounded down, with ❗️ after a part below 5% of the memory or 5 GB of disk. It reads the disk of the data folder, or of its nearest existing parent when the folder is missing, and sends neither to the service. It sends the effort level and the limits with the session, the process and the mark of the status line, prints its line without a service, sends nothing without either, and loads only Node modules,paths.tsandservice-request.ts. The service writesstatus-line.js, which runs the status line command of its own build, in place of an older one. The records follow sessions recorded with Claude Code 2.1.322 on 2026-11-12. The hooks, the session server and the service are tested with the environments of twoclaude -pruns, recorded with Claude Code 2.1.319 intest/unit/claude-p-runs.jsonl. One run has the entrypointclaude-vscodeof a VS Code session, and the other is a plainclaude -prun. The session server must answerserver/discoverwithMethod not foundand negotiate the revision 2025-11-25. Claude Code 2.1.319 registers no channel for a server in the modern MCP era, 2026-07-28, so this test fails after an SDK upgrade that turns that era on. -
npm run test:e2e, filetest/e2e/launch.test.ts, installs a copy of the package withnpm ciand packs it, asbuild.ymlpublishes it. The test checks these facts:- The tarball has no lockfile.
- Its top-level entries are the build,
node_modulesand the plugin files. - Exactly the production packages of
package-lock.jsonare in itsnode_modules. - Unpacked, with nothing installed, the package runs a hook and the session server with the commands of
hooks/hooks.jsonand.mcp.json. - Installed into a project offline, from the tarball alone, the package keeps its modules in its own folder, and
simplex-mcpruns. - The status line setting, run by
sh, prints the status line throughstatus-line.jsof the data folder, which runs the unpacked package's command, withSIMPLEX_MCP_HOMEand with~/.simplex-mcp.
-
npm run test:e2e, filetest/e2e/service.test.ts, runs with a local smp-server and xftp-server:- An owner joins the Main group and the groups of two sessions, and approves
connect,send,downloadandleavethere. The owner's copies of the sessions' groups have the chat layoutterminal, and the Main group has none. Chats belong to their sessions, and the owner moves one to the other session with/give./listworks after a service restart. The short description and the welcome message that the owner set in the Main group stay after the restart. - The Main group shows the list of sessions after the owner joins. The attached session's line follows the record file that its
/sessionnames: working, waiting for you with the card of a permission request, idle, and the last line after it detaches. Each change edits the same message, and/sessionsreplies with the same text. - While files and media are off in a session's group, the card of a
sendof an image is text. After the owner's approval, the image message reaches the bot with its caption and its file, and the card is edited as text. - While SimpleX links are off in a session's group:
- A
sendcard is posted with the local server's SimpleX link at the end of its code span, because the core does not detect a link whose query is followed by the closing backtick. - For a terminal prompt with a SimpleX link, Claude posts
User's prompt was not posted: SimpleX links are not allowed for User in the group of this session; its owners can allow them in the group's preferences. - For an answer with a SimpleX link,
Claude's answer was not posted: SimpleX links are off in the group of this session; its owners can turn them on in the group's preferences.fills the turn's opening message. - A
sendwith a preset server's SimpleX link under a standing approval reaches the bot and returnsdone. In place of its card, Claude postsAction 2 was performed; its card was not posted: SimpleX links are off in the group of this session; its owners can turn them on in the group's preferences. - A bot's welcome message has a preset server's SimpleX link, which has no query. The
connectcard of that bot is not posted, and neither is asendcard with that link. Claude postsAction 2: SimpleX links are off in the group of this session; its owners can turn them on in the group's preferences.andAction 3: ...instead. Both calls returnfailedwith the text afterAction N:.
- A
- While SimpleX links are on for admins only in a session's group, Claude's answer with a SimpleX link is posted.
Useris a member and can't post the terminal prompt with that link, so Claude postsUser's prompt was not posted: SimpleX links are not allowed for User in the group of this session; its owners can allow them in the group's preferences. - The hooks post a prompt typed in the terminal as
Userand the answer as Claude. The session's first prompt is posted also when its hook starts before the transcript file is created. A task notification is not posted byUser. Claude posts its line,✅ Background command "Build" completed (exit code 0). For a failed task added to the running turn as a queued command, Claude posts❌ Background command "Lint" failed with exit code 1. For a compaction of the session after/compact, Claude posts⚙️ Context summarised on request: 399K → 25K tokenswithout a quote. The group's short description shows the model of the first answer, read from the transcript. Claude repliesSession 1 is not running.to an owner's message to a session without Claude Code. The reply has no quote when the message is as long as the member's core sends. With the session attached, the service passes the owner's message to the session's channel stream.Userdoes not post it again, raw or in the channel tag, and Claude quotes it in the answer. The owner's reply to Claude's answerLint passes.reaches the stream after the quote line> Lint passes., without the answer's end line, with the answer's ID and the senderClaude. Before the session attaches, the owner's reaction to Claude's answerFixed.getsSession 1 is not running., quotingFixed.With the session attached, the owner's 👍 toTests pass.reaches the stream after the quote line> Tests pass., with the answer's ID asitemandreplyTo.itemand the senderClaude. The opening message of its turn quotesTests pass., and the answer fills it. A removed reaction reaches no session. A PreToolUse hook of Bash posts💻 Run the testsfrom Claude as a live message, and its PostToolUse hook with 2018 ms updates it to💻 Run the tests ✅ 2.0 s, no longer live and not edited. The answers fill the opening messages of their turns, which quote the owner's prompts. For the owner'sSummarize, the opening message is live; two runs ofdist/display.jsstreamSummary:andAll green.into it, and it stays live. At the Stop hook ofFix the build, the answer ends with the end line!- Done in 2.0 s · 861 output tokens · 36K tokens in context · RAM N GB free · disk N GB free!, with the usage from the transcript. Each other answer ends with an end line too. After a status line report, the Stop hook ofSummarizecompletes its message with an end line with· 5 h: 34% · week: 61%before the memory and the disk, no longer live and not edited, and the answer is not posted again. - Hooks with a new session ID, from the process of an attached session, post in that session's group. After the owner approves a tool-use card, the service sends
allowon the session's stream. After the owner's/approve N allof the next card, Claude repliesApproved `Bash` for the rest of this session by Alice. /revoke Bash, and the stream gets the approved tools andallow. A contact and a group that accept afterconnectreturnedconnected: falseare in the session'slist. Modehostapplies after the owner approves its card, and no mode is written to session.json. After a service restart, a prompt sent before the session attached again is passed to the session, withoutSession 1 is not running. - A member joins the Main group with an owner's link:
- The member sees the Main group's short description and welcome message of trust, and Claude posts the join there.
- The member joins a session's group as an admin with
/join. Claude posts the rights of an admin there, with the/observercommand. - The member prompts and approves a tool-use card in the session's group, even after removal from the Main group. Claude replies
Unknown command.to the member's//compact, and the session does not get it. - A member added to the session's group with a group link, as a member, prompts. Claude posts the rights of a member for that member. Claude refuses that member's
/pendingand/!lsonce each, with the same text. - A file of
replyreaches the group at once. After the owner turns off the group's files, the next one fails withFiles and media are off in the group of this session; its owners can turn them on in the group's preferences. - Each join is posted once, in the Main group and in the session's group.
- The owner makes the added member an admin in the app. Claude posts the admin's rights, and the member's
/pendingthen works. - With the command of a join post, the owner makes that member an observer. Claude replies with the observer's rights, and the member's app then refuses to send.
- The observer's reaction reaches the owner and no session. The reaction of the member from the Main group to the tool-use card reaches the session.
- After a change of the model, the group's files stay off, because Claude updates the group's profile from its current state.
reset-ownersreplaces the Main group at once while the owner is in it, without the owner's approval. Run without a terminal, it says to runlinkin a terminal. Run in a terminal, it prints the new link with its QR code.- Both members from the Main group keep their roles in the session's group, and they still prompt and approve there.
- An admin from the Main group approves all messages to a chat, and Bash for the rest of the session. After the owner's
/observerof that admin,/listshows the chat without the approval and no approved tool, and the session's stream gets an empty list of approved tools. Claude repliesNo member ID in this group.to/observerof a member who has sent/join 1but has not joined yet. The member then joins as an admin. - A data folder of 0.3.0, whose
Userhas the peer typeagent, starts withUserashuman, and the hub's contact ofUsergetshumantoo. An owner who then joins a session's group sees Claude withagentandUserwithhuman. - A new session has no chats.
- A stdio session starts the service. It recovers after the service is killed during a call. It starts the service again and attaches without a call.
- A SessionStart hook is ended with its descendants while its service starts, as Claude Code ends its hooks when it exits. The service keeps starting, and the next session start shows the link of that service.
- A Main group named
SimpleX MCPis renamedClaude Controlat the next start of the service with the default options.
- An owner joins the Main group and the groups of two sessions, and approves
Time of the display hook
Claude Code shows each batch of Claude's text in the terminal only after the display hook returns. To measure the hook, run node dist/display.js with a MessageDisplay input and SIMPLEX_MCP_HOME of a folder with service.token and an HTTP server on service.sock that answers 200 at once, alternating with node -e 0. On 2026-11-13, at a load average of 20, 20 runs of each took a median of 113 ms, from 76 to 172 ms, for the hook and 63 ms for node -e 0. The median difference was 49 ms.
Checks in a real session
In a session started as in step 2 above:
-
At the session start, Claude Code shows
SimpleX MCP: scan this QR code with the SimpleX app and tap Join to supervise your agents in "Claude Control":, a QR code and the link. Ask Claude which link was shown at the session start. Claude doesn't know it. If Claude Code refusesplugin:simplex@inlinewith the development flag, checks 3, 5, 6, 7, 8 and 21 wait for the published plugin andplugin:simplex@simplex-chat. -
Scan the QR code in the SimpleX app and tap Join. In "Claude Control", tap the invitation to "1 · " and join it. The group opens in the Flat layout, and Group info ›
Chat theme›Chat layoutshowsFlat (chat). "Claude Control" is shown in your own layout. -
Send
Reply with the word ready.in "1 · ". The answer comes from Claude, as a reply to your message. In an app that shows peer types in groups, Claude has the agent placeholder, three dots, andUserthe person placeholder. -
Type a prompt in the terminal. It appears in the group from
User, and the answer appears from Claude. Record whether a prompt from the group also appears fromUser, because Claude Code's documentation does not say whether a channel prompt runs the UserPromptSubmit hook. Ask Claude to runsleep 5with Bash in the background. When the task ends, its notification does not appear fromUser; Claude posts a line in small print that starts with ✅ instead. Ask Claude to start a background agent that replies with one word, and to schedule a one-time prompt with CronCreate two minutes ahead. Each appears as one line in small print from Claude. While Claude runs a foreground command, type a prompt in the terminal: it appears fromUser. Ask Claude to read a file and runsleep 12with Bash. A line from Claude appears for each step when it starts,📖 Read PATHand💻 ..., shown as live while the step runs, all in small print, and each is completed with its duration,12 sfor the sleep, without ✅ and without an edited mark. With an app that supports silent messages, the lines, the notes and Claude's texts do not alert, and an answer posted as a new message, with its end line, does. -
Send
Count from 1 to 300, one number per line.in the group, and at once sendReply with the word two.The second prompt waits in Claude Code's queue. Claude quotes the first message in the answer with the numbers, and the second message in the answertwo. Neither prompt appears fromUser. The hub chooses the quote of each answer by the start times of the Stop and UserPromptSubmit hooks, and this check confirms that. Then reply to Claude's answer of check 3 withSay it again in capitals.Claude answers in capitals with the word of check 3, as a reply to your message. Send a photo, and reply to it withWhat is in this photo?In the transcript, the tag of the first reply containsreply_to_from="Claude", and its content starts with>and that answer; the content of the second starts with> image:and the photo's file name. -
React 👍 to Claude's answer of check 3. Claude answers as a reply to that answer, and
Userposts nothing. In the transcript, the tag hasreply_toequal toitem, and its content is>and that answer, with 👍 on the next line. Remove the reaction, and nothing happens. SendCount from 1 to 300, one number per line., and react ❤ to that message while Claude counts. Claude answers the reaction in the next turn, as a reply to that message. -
Send
//helpin the group. A one-line message that starts with/is a command of the group, so Claude repliesUnknown command., and the session gets nothing. Send!git status. The session gets it as a prompt, and Claude answers it. Claude Code never runs a command from a channel prompt. Claude Code 2.1.319 was checked on 2026-11-08 with a test channel. It ran neither a command nor a shell command from a channel prompt that started with/or!, and it passed the text to Claude in the<channel>tag. After/model sonnet, the model was unchanged, and after!echo, no file was written. In the code of Claude Code 2.1.322, a channel message is queued as a prompt withskipSlashCommandsset. Claude may act on such a text with its tools, such as Bash, under the tool-use approval of check 8. -
Send
Run ls with Bash.in the group. The terminal shows the permission dialog, and Claude posts the cardI want to use `Bash`: ...with/approve N, /approve N all or /reject Nin the group. Tap/approve N, andlsruns. Ask again and tap/reject N, and Claude reports the refusal. Answer a third request in the terminal. When the turn ends, Claude ends its card withEnded.Then ask forlsagain and tap/approve N all: Claude replies that Bash is approved for the rest of this session. Ask forpwdwith Bash: it runs without a card and without the terminal's dialog. Ask Claude to append a line to.bashrcin the project folder with Bash: the terminal shows the dialog, and the card has the line that Bash is approved and Claude Code still asks. Send/revoke Bash, and the next Bash use gets a card again. Approve Bash for the session once more, exit, and start with--continue: the next Bash use gets a card. Checked on 2026-11-13 with Claude Code 2.1.323 inclaude -pruns: a PreToolUse hook of typemcp_toolthat answersallowlet Bash and a Write ofnotes.txtrun, and Claude Code still refused a Write of.bashrc; with the plugin loaded from its folder, the hook calledplugin:simplex:simplex/pre_tool_usebefore a Bash use, and its empty answer left the decision to Claude Code. -
The short description of the group shows
MODEL · effort LEVELafter the first answer. It shows the model in a session started with--resumetoo, because the Stop hook reads the model of the answer from the transcript. After/modelin the terminal, the description shows the new model, and Claude postsModel changed to MODELin small print. A change of the effort level shows at the next tool step or answer, withEffort changed to LEVELbefore it. The end line of each answer shows the turn's time, output tokens and tokens in context. Then start the session with the status line setting of REFERENCE in a settings file passed by--settings: the terminal shows the status line with the plan's usage, each end line ends with5 h: N% · week: N%,/effortposts its line at once, and a prompt withultrathinkposts no effort line. This was checked with Claude Code 2.1.322 on 2026-11-11, inclaude -pruns with a Stop hook from--settings. The answer's entry in the transcript, of typeassistantwithmessage.model, was written 26 to 71 ms after the hook started. The SessionStart hook got nomodel. Run/compactin the terminal. Claude posts⚙️ Context summarised on request: PRE → POST tokensa few seconds after the summary, and the description keeps the session's model. Start Claude Code with--agents '{"small": {"description": "A small agent", "prompt": "Read the files you are given.", "model": "haiku", "autoCompactWindow": WINDOW}}', WINDOW the smallest that Claude Code accepts, and ask Claude to havesmallread large files until its context is summarised. Claude posts no line for that compaction, and the description keeps the session's model. -
Run
/clear, and then sendReply with the word cleared.in the group. The answer comes in the same group, and no group "2 · " appears. -
Stop the service:
kill $(cat /tmp/simplex-mcp-test/service.lock). After 30 seconds, without a tool call, sendReply with the word back.in the group. The answer comes in the group. -
Exit Claude Code. Within 10 minutes, while the service runs, send a message in the group. Claude replies
Session 1 is not running. -
Start Claude Code again as in step 2, with
--continue. No new group is opened at the session start, and a prompt from "1 · " reaches the session. -
In a second terminal, start Claude Code as in step 2 in another folder, and exit it. The group "2 · " appears. In the first session,
/resumethat session, and sendReply with the word resumed.in "1 · ". The answer comes there. Exit, and start Claude Code with--resumeof that session. A prompt from "2 · " reaches it. -
In another folder, run
SIMPLEX_MCP_HOME=/tmp/simplex-mcp-test claude -p "Call the list tool of the simplex server." --plugin-dir /tmp/simplex-plugin. No new group appears, and the answer containsThis Claude Code run is not interactive, so it has no SimpleX group. This was checked with Claude Code 2.1.322 on 2026-11-11, with a folder that held only the unpacked package. The answer contained the text, and the folder had nonode_modules/.package-lock.json, the record of an npm install. -
Record which values of
CLAUDE_CODE_SESSION_ATTENDEDthe hooks and the MCP servers of a run get. Write the MCP config and the hook settings:echo '{"mcpServers": {"dump": {"command": "node", "args": ["-e", "require(\"fs\").writeFileSync(\"/tmp/env-mcp.json\", JSON.stringify(process.env))"]}}}' > /tmp/env-mcp-config.json echo '{"hooks": {"SessionStart": [{"hooks": [{"type": "command", "command": "node -e \"require(\\\"fs\\\").writeFileSync(\\\"/tmp/env-hook.json\\\", JSON.stringify(process.env))\""}]}]}}' > /tmp/env-settings.jsonRun
claude -p "Reply with ok." --strict-mcp-config --mcp-config /tmp/env-mcp-config.json --settings /tmp/env-settings.jsontwice. Run it once in a terminal, and once from the Bash tool of the session of step 2, withCLAUDE_CODE_ENTRYPOINT=claude-vscodebefore it. After each run,grep -o '"CLAUDE_CODE_SESSION_ATTENDED":"[01]"' /tmp/env-hook.json /tmp/env-mcp.jsonshows the values. The results with Claude Code 2.1.319 on 2026-11-08:- In a terminal, the hook got
0, and the MCP server got no value. - From the Bash tool, the hook got
0, and the MCP server got1, the value of the session whose Bash tool ran it. The hook'sCLAUDE_PIDis the parent process of the MCP server.
For the second run, the plugin's SessionStart hook marks that process in the service, and the service refuses its session server.
- In a terminal, the hook got
-
From the Bash tool of the session of step 2, run
CLAUDE_CODE_ENTRYPOINT=claude-vscode SIMPLEX_MCP_HOME=/tmp/simplex-mcp-test claude -p "Call the list tool of the simplex server." --plugin-dir /tmp/simplex-pluginin another folder. No new group appears, and the answer containsThis Claude Code run is not interactive, so it has no SimpleX group. -
Load the plugin from settings, as in Shared settings, with a plugin registry of its own:
mkdir -p /tmp/simplex-plugins/.claude-plugin cp -r /tmp/simplex-plugin /tmp/simplex-plugins/plugin echo '{"name": "simplex-local", "owner": {"name": "Test"}, "plugins": [{"name": "simplex", "source": "./plugin"}]}' > /tmp/simplex-plugins/.claude-plugin/marketplace.json echo '{"extraKnownMarketplaces": {"simplex-local": {"source": {"source": "directory", "path": "/tmp/simplex-plugins"}}}, "enabledPlugins": {"simplex@simplex-local": true}}' > /tmp/shared-settings.jsonIn another folder, run
CLAUDE_CODE_PLUGIN_CACHE_DIR=/tmp/claude-plugins-test SIMPLEX_MCP_HOME=/tmp/simplex-mcp-test claude -p "Call the list tool of the simplex server." --settings /tmp/shared-settings.json. The answer containsThis Claude Code run is not interactive, so it has no SimpleX group. WithCLAUDE_CODE_PLUGIN_CACHE_DIRset, Claude Code registers the marketplace outside~/.claude/plugins. The results with Claude Code 2.1.322 on 2026-11-11:- The answer contained the text.
/tmp/claude-plugins-test/known_marketplaces.jsonlistedsimplex-local.- The plugin's folder had no
node_modules/.package-lock.json. - With the same keys in
.claude/settings.jsonof the folder, and without--settings, the run had no tool of the plugin.
-
Start Claude Code as in step 2 with an empty data folder and a machine name:
SIMPLEX_MCP_HOME=/tmp/simplex-mcp-fresh SIMPLEX_MCP_MACHINE=laptop claude --plugin-dir /tmp/simplex-plugin --dangerously-load-development-channels plugin:simplex@inline. Exit it before the QR code shows. Start it again the same way. The QR code shows within seconds, for the group "Claude Control - laptop". Stop that service:kill $(cat /tmp/simplex-mcp-fresh/service.lock). -
With the session of step 2 running and a second session started as in step 2 in another folder, the Main group shows the list of sessions, one line for each. Ask Claude to run
sleep 20with Bash: its line shows 🟠 working. SendRun ls with Bash.in its group: the line shows 🔵 waiting for you, 1 approval; tap/approve N, and it shows 🟠 working, then 🟢 idle when the turn ends. Press Esc during a turn: the line shows 🟢 idle within 2 seconds, although Claude Code runs no Stop hook. Ask Claude to ask you a question with AskUserQuestion: the line shows 🔵 waiting for you in Claude Code. Exit the second Claude Code: its session moves into the last line,⚪ Not running:./sessionsreplies with the same text. -
Send
Read README.md, say what you are doing before each step, and then summarize it in 30 lines.in the group. An empty message from Claude appears at once, as a reply to your message, with typing dots. Claude's first remark or step fills it, and each later remark and the answer appear from their first line, growing by whole lines, at most every 3 seconds. The steps' lines appear between them. Each message ends without an edited mark. The answer's message ends withDone in, the turn's time and tokens in small print, and the chat list shows the answer. In the terminal, Claude's text appears by whole lines. -
Stop the service:
kill $(cat /tmp/simplex-mcp-test/service.lock).