Files
Evgeny @ SimpleX Chat b475ae25ac mcp: free memory and disk in the end line of answers (#8211)
* 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%
2026-11-14 23:17:25 +00:00

138 KiB
Raw Permalink Blame History

SimpleX MCP server: API

The six MCP tools, the agent control chat commands, replies and cards, and the CLI of @simplex-chat/mcp 0.3.0. The Claude Code plugin's tools, groups, channel, socket protocol, commands and files are in section 4.

Related specs: README | Architecture | Flows

Source: tools.ts | control.ts | cli.ts | messages.ts | actions.ts | session.ts | service.ts | hub.ts | main-group.ts | hook.ts | owner.ts | protocol.ts


Table of contents

  1. Tools
  2. Agent control chat
  3. CLI
  4. Claude Code plugin

1. Tools

1.1 Common rules

Rule Code
Tools are registered on each per-request McpServer with description, input schema, output schema and, in mode host, _meta: {"anthropic/requiresUserInteraction": true} for connect, send, download and leave definitions, registerTools, AgentTools.register
Tool descriptions and server instructions; the instructions name the agent's display name connectDescription to leaveDescription, instructions, startAgent
Arguments are validated by the SDK; a failure is a result with isError: true and the text Input validation error: Invalid arguments for tool NAME: ERRORS McpServer.validateToolInput
additionalProperties: false is set in every input schema connectSchema, sendSchema, receiveSchema, listSchema, leaveSchema, downloadSchema
A result is sent as structuredContent and as its JSON in one text item AgentTools.call
A tool error is sent as isError: true with one text item: the ToolError text, or the errorText of other errors AgentTools.call, errorText
An aborted call ends with the result Cancelled., isError: true, which the SDK discards cancelled, registerTools
With a progressToken in _meta, notifications/progress is sent at the start of each wait and every 60 s, with progress 0, 1, 2, ... and a message toolCall, reportProgress
The call is aborted when the client closes the response stream or sends notifications/cancelled; the action is kept Protocol._oncancel, _onclose
A call with the same tool and action fields as an action in memory is attached to it. The key is the JSON array of the session number, the tool and the fields, with the session number undefined for serve actionKey, AgentTools.action, Actions.find
Messages are marked read after the last wait of a call that is not aborted AgentTools.connectedChat, sendResult, receive

Action fields of the key:

Tool Fields
connect target
incognito (default false)
message (default null)
send chat
text (default null)
file (default null)
as (default null)
reply_to (default null)
mention (default null)
download chat
item
leave chat

Result status of the four action tools (actionResult):

Status Meaning Extra fields
done performed per tool
failed failure of the card post, the counter write or the perform, or loss of the control chat error
rejected an approver sent /reject
expired no decision before the expiry time
known connect only: the target is an existing chat past the prepared state; no action chat fields
performing download only: wait passed after the approval; the download continues

1.2 connect

Handler: AgentTools.connect. Perform: performConnect. Schemas: input connectSchema, output connectOutput.

Input:

Field Type Range Default Rule
target string 1 character or more required SimpleX link (https://..., simplex:/...), contact name @name.simplex or channel name #name.simplex; whitespace refused
incognito boolean false true: the join methods take incognito true
message string 1 to 2000 characters first message of a contact request; plans with takesMessage only
wait number 0 to 86400 60 seconds from the approval: for the other side to accept and, with message, for its first reply
idle number 1 to 300 30 seconds without a new message, after which the server ends the wait for messages

Output fields by case:

Case Fields Code
known status and the chat fields of the known chat. The plugin's rules for a known chat are in 4.1 AgentTools.connect, ownChat
done, chat unknown action, status, type, connected: false, plan fields name, peer_type, description, welcome, commands, known_as when present AgentTools.connectResult, planFields
done, chat known action, status, chat fields, messages AgentTools.connectedChat
failed action, status, error AgentTools.actionResult
rejected, expired action, status AgentTools.actionResult

Chat fields (chatFields):

Field Contact Group, business chat or channel
chat @contactId #groupId
type contact business with businessChat; channel with useRelays or group type channel; otherwise group
name profile display name group display name
simplex_name @ + contactDomain.domain when verified # + groupDomainClaim.domain when verified
peer_type profile peer type, when present from the plan, when present
description profile shortDescr group shortDescr
welcome from the plan: link data message group description
commands profile preferences.commands groupPreferences.commands
known_as incognito: customUserProfile of apiContactInfo incognito: the membership's display name
role the agent's member role
connected active connection status ready membership status connected or complete

messages: message items among the last 50 items of the chat when the result is built, replaced by their collected copies, followed by the items collected since the connection; live items are left out; new items are marked read (AgentTools.connectedChat).

Tool errors:

Text Condition Code
Not a SimpleX link or name: TARGET whitespace in target, or invalidConnReq from apiConnectPlan AgentTools.plan
an app error text, for example Name not found: This SimpleX name is not registered. Please check the name., or SimpleX error: CHAIN: DETAILS other errors of apiConnectPlan, or a plan of type error AgentTools.plan, classifyPlan, chatErrorText
TARGET can't be joined now: PLAN. invitationLink other than ok and known
contactAddress other than ok, known, contactViaAddress and connectingConfirmReconnect
groupLink other than ok, known and connectingConfirmReconnect
notJoinable in classifyPlan
message: TARGET is not a contact or business address with short link data, or its contact exists without a connection. message given and the plan has takesMessage: false AgentTools.connect
refusals see 1.9

takesMessage is true for a contact address with short link data, for a known prepared contact, and for a known prepared business group (classifyPlan).

1.3 send

Handler: AgentTools.send. Result: sendResult. Perform: performSend. Schemas: input sendSchema, output sendOutput.

Input:

Field Type Range Default Rule
chat string required @N or #N of the agent
text string 1 to 12000 characters required without file the message text, or the caption of file
file string 1 character or more absolute path of a file of this computer
as string file sends an image or video unchanged, as a file; only with file
reply_to integer 1 or more item ID of a message in chat
mention integer array 1 to 3, unique, each 1 or more member IDs of a group; names missing from text are prefixed as @name
wait number 0 to 86400 60 seconds from the send; from the call when it attaches to a done action
idle number 1 to 300 30 seconds without a new response, once one arrived
limit integer 1 to 100 50 most responses returned

File types by extension, lower-cased (attachmentTypes, otherFile, attachmentMedia):

Extension Message type Sent file Preview and duration
.jpg, .jpeg, .png image core.resizeImage(..., Image), written to DATA/files/sent/; the original when resizing fails core.resizeImage(..., MessagePreview); the fixed preview when it fails
.gif, .webp image unchanged the fixed preview
.mp4, .mov video unchanged the first frame from ffmpeg, resized as a preview; duration from ffprobe, rounded; the fixed preview and 0 when they fail
other, or as: "file" file unchanged

The fixed preview is a 16 × 9 mid-gray PNG (fixedPreview). ffmpeg and ffprobe run with -protocol_whitelist file -f mov, 30 s and 64 MB of output each (videoFrame, videoDuration, commandOutput).

Output:

Field Presence Value
action always action number
status always done, failed, rejected, expired
chat done the chat reference
item done item ID of the sent message
responses done received message items with IDs above item, in arrival order, live items left out, at most limit
more done collected responses not returned, live ones and overflow included
error failed error text

Tool errors:

Text Condition Code
text: required without file. neither text nor file AgentTools.send
as: applies only with file. as without file AgentTools.send
No chat CHAT. list shows the agent's chats. invalid reference, the control chat, or a store error when the chat is read AgentTools.knownChat, unknownChat
The agent is not connected to CHAT and can't post; list shows connected: false. the chat is not connected AgentTools.send
The agent has role ROLE in CHAT and can't post. membership role observer or relay AgentTools.send
reply_to: CHAT has no item N. the read of around=N fails, or the item is absent from it AgentTools.quotedItem
reply_to: item N in CHAT is not a message. the item's content is not rcvMsgContent or sndMsgContent AgentTools.quotedItem
mention: CHAT is a contact chat; mentions apply to groups and channels. mention with @N AgentTools.mentionedMembers
mention: CHAT has no member N. ID absent from apiListMembers AgentTools.mentionedMembers
mention: members N and M have the same name. two mentioned members with the same display name AgentTools.mentionedMembers
file: an absolute path is expected.
file: no file at FILE.
file: PATH is not a file.
file: PATH can't be read.
the path, after symbolic links realFile
file: PATH is refused: private keys and the server's own files are not sent. a file named id_*, *.pem, *.key, *.p12 or *.pfx, or under ~/.ssh, ~/.gnupg, or the data folder or ~/.simplex-mcp outside DATA/files/; each folder by its real path AgentTools.attachment, isRefused
file: PATH is empty. size 0 AgentTools.attachment
text: too long for the message with its quote; shorten it.
text: too long for a message with this TYPE; shorten it.
the message, as the core sends it, above 15602 bytes AgentTools.send, tooLongText, fitsMessage, quoteContent
refusals see 1.9

The message is measured as 600 bytes plus the JSON of its content, the file's name, the quote and the mentioned names. The quote is the quoted text, or its file's name when the text is empty; a sent image or video quotes it as text, otherwise an image's preview is kept (fitsMessage, quoteContent).

The perform fails with file: PATH changed after the request. when the file's real path, size, inode or change time differs from the request (AgentTools.fileToSend). A resized copy is deleted at sndFileCompleteXFTP, at sndFileError and after a failed send (AgentTools.performSend, onSentFile, deleteSentCopy, isSentCopy, onEvent).

1.4 receive

Handler: AgentTools.receive. Schemas: input receiveSchema, output receiveOutput.

Input:

Field Type Range Default Rule
chat string required @N or #N of the agent
wait number 0 to 86400 0 seconds to wait when no message is new
limit integer 1 to 100 50 most messages returned

Output (all fields always present):

Field Value
chat the chat reference
messages unread received messages in chat order, then received messages that arrived during the call; live items left out; at most limit
more new messages not returned, overflow, and unread items left unread by the page reads

Tool errors: No chat CHAT. list shows the agent's chats. for an invalid reference, the control chat, or a store error of the first read, initial 1 (AgentTools.receive); other chat errors, a store error of a later page read included, as their error text (errorText, chatErrorText).

Messages are read by receive without an action or an approval.

1.5 download

Handler: AgentTools.download. Result: downloadResult. Perform: performDownload, downloadFile. Schemas: input downloadSchema, output downloadOutput.

Input:

Field Type Range Default Rule
chat string required @N or #N of the agent
item integer 1 or more required item ID of a received message with a file
wait number 0 to 86400 60 seconds from the call to wait for the sender's upload before the card; seconds from the start of the perform, or from a call that attaches to a performing action, for the download

Output:

Field Presence Value
action always action number
status always done, performing, failed, rejected, expired
chat, item done the message
path done DATA/files/FOLDER/<file ID><extension>
error failed error text

FOLDER is group-N for #N and contact-N for @N; the extension is the file name's extension when it has 1 to 16 ASCII letters and digits (filePaths, storedName, chatFolder). /forward downloads a file to DATA/forwarded/FOLDER/ under the same name; a later perform of the download moves it to the download path, after the copy for the post is made (AgentTools.downloadFile, forwardFile).

Steps before the action:

Step Code
a file in status rcvInvitation, or an XFTP file: the file's servers from apiGetChatItemInfo; while none, the call waits for rcvFileDescrReady until wait seconds after the call, with the progress The sender is uploading the file of item N in CHAT; waiting until TIME. AgentTools.fileServers
unknown servers: the file's servers that are not among the XFTP servers of apiGetUserServers, of no operator or of an enabled one, compared without their passwords AgentTools.unknownServers
without unknown servers, and for a file ID not in rejected files, the chat's files approval, read again, makes the action performed at once AgentTools.download

Perform: apiReceiveFile(fileId, path, approvedRelays), for a file in status rcvInvitation. approvedRelays is true when the action's mode is requests and unknown servers are named on its card, and false otherwise. The core then checks the complete description (AgentTools.downloadTo, startDownload). The download ends at rcvFileComplete, rcvFileError, rcvFileSndCancelled or chatItemUpdated of its file, or at a check every 60 s (AgentTools.onFile, onFileComplete, onFileError, onFileCancelled, checkDownload, currentFile, settleFile, settleReceived, moveReceived, failDownload, settleDownload).

Failure texts of the perform:

Text Condition Code
the file's error, as in the file field the file failed AgentTools.settleFile
The sender cancelled the file. rcvFileSndCancelled AgentTools.onFileCancelled
The message or its chat was deleted. a check finds no message, contact or group deletedItem, AgentTools.currentFile
The download made no progress for 30 minutes and was cancelled. no rise of rcvProgress for 30 minutes; the file is cancelled stalledDownload, AgentTools.checkDownload
The received file is not in the agent's files folder. the file is received and neither the download path nor the forwarded path has a file missingFile, AgentTools.settleReceived
Your owner deleted the files of this chat. /delete CHAT files deletedFiles, AgentTools.deleteChatFiles
The file is on unknown servers that were not approved. a check reads an accepted file in status rcvInvitation: the core returned it to the offer when its description completed unapprovedServers, AgentTools.checkDownload
Unknown servers! Without Tor or VPN, your IP address will be visible to these XFTP relays: HOST, HOST. the core refuses the servers of the complete description at the acceptance chatErrorTypeText

Tool errors:

Text Condition Code
No chat CHAT. list shows the agent's chats. invalid reference, the control chat, or a store error when the chat is read AgentTools.download
item: CHAT has no item N. the item is not found AgentTools.download
item: item N in CHAT has no received file. the item is not received or has no file AgentTools.download
item: the file of item N in CHAT failed: ERROR the file field has status failed AgentTools.download
item: the sender has not uploaded the file of item N in CHAT yet; call download again later. no servers by the end of wait, also for a file invited without a description, whose servers the core does not list; no action is created AgentTools.download, fileServers
refusals see 1.9

A file ID whose download returned rejected or expired shows status rejected until a download of it is done or the server restarts (AgentTools.downloadResult).

1.6 list

Handler: AgentTools.listChats. Schemas: input listSchema, output listOutput.

Input: an empty object.

Output:

Field Item fields
chats chat
type
name
simplex_name, when verified
peer_type, when present
incognito
known_as, when incognito
connected
unread: chatStats.unreadCount
approved: true, only under a standing approval of messages in mode requests
actions action
tool
input: the input of the creating call
state
open: true while a call waits on it

chats: the contacts and groups of the main conversations from one read, apiGetChats(USER, last 1000000), except the control chat. In the plugin, only the chats of the calling session are listed (AgentTools.agentChats, owns). actions: the actions in memory of the calling session other than its mode and tool-use cards, or all actions for serve (AgentTools.listChats).

1.7 leave

Handler: AgentTools.leave. Perform: leaveChat. Schemas: input leaveSchema, output leaveOutput.

Input: chat, string, required, @N or #N of the agent.

Output:

Field Presence Value
action always action number
status always done, failed, rejected, expired
chat done the deleted chat
error failed error text

Perform:

Chat Methods
@N apiDeleteChat(Direct, N, full, notify)
#N apiLeaveGroup(N) while the membership is current, pending_approval or pending_review
apiDeleteChat(Group, N, full, notify)

Tool errors: No chat CHAT. list shows the agent's chats. when no action with the same key is in memory and the chat is invalid, the control chat or unknown (AgentTools.leave); refusals.

1.8 Message, file and command objects

Message (Message, toMessage, schema messageSchema):

Field Type Presence Source
chat string always chat reference of the item
item integer always meta.itemId
from string always groupRcv: member display name
directRcv: contact display name
channelRcv: channel display name
sent items in connect: the agent's name in that chat
from_member integer groupRcv groupMemberId
from_type string when the profile has a peer type sender's peerType; the agent's own for its non-incognito items in connect
time string always meta.itemTs
text string always msgContent.text
file object a received item with a file below
new boolean always item status rcvNew when read
reply_to object a quoted item below
mentions_me boolean always meta.userMention

Quote, reply_to (toReplyTo, replyText, trimmed):

Field Presence Value
chat always chat reference of the item
item the quoted item is in the chat quotedItem.itemId
from the sender is known by quotedItem.chatDir:
groupRcv: member display name
directRcv: contact display name
groupSnd, directSnd: the agent's name in that chat, its incognito name in an incognito chat
channelRcv, a member unknown to the chat: absent
type a quoted message other than a text quotedItem.content.type: link, image, video, voice, file, report or chat; absent for text and unknown
text always the first line of quotedItem.content.text, trimmed, up to 200 characters, and … when the line is longer or more lines follow. A line ends at \n, \r, \r\n, \v, \f, U+0085, U+2028 or U+2029. The bidi controls U+202A-U+202E and U+2066-U+2069 are removed. Characters are grapheme clusters, by Intl.Segmenter, so an emoji sequence is never split, and the space before … is dropped. The replier's core puts the file name in place of an empty text for a quoted image or file

connect, send and receive name the agent by the chat of the returned items: its profile name, or its incognito name in an incognito chat, as known_as (AgentTools.selfSender, toMessages). When the incognito name of a contact can't be read, the profile name is used and the error is logged, so the result keeps the messages that the call marked read.

File (messageFile, receivedFileError):

Field Value
name fileName
size fileSize, bytes
type image, video or voice from the message type; file otherwise
status first match:
rejected: the file ID is in rejected files
failed: fileProhibited is set, the status is rcvCancelled, rcvAborted, rcvError or invalid, or the status is rcvComplete and neither the download path nor the forwarded path has a file
received: rcvComplete, a file at the download path, and fileSource at the download path or the forwarded path
offered: otherwise, a file that /forward downloaded included
path received: the download path
error failed: the error text (fileError, fileStatusError, fileErrorText, srvErrorText)

Only received message items (rcvMsgContent) are returned by send and receive; connect also returns sent ones (sndMsgContent) (ChatItemsWatch.collect, AgentTools.connectedChat).

Command (commandsOf, schema commandSchema):

Form Fields
command keyword
label
params, when present
menu label
commands: commands and menus

1.9 Action refusals

The plugin's refusals are in 4.4. Refusals of a new connect, send, download or leave action of serve, first match (Actions.create, Control.refusal, hasApprover):

Text Condition
The server is stopping. Actions.stop has started
The agent lost its control chat. The person who runs it has to restart it with --reset-owners. control chat lost
20 actions are pending; wait for the owner's decisions. 20 actions in state pending
20 actions are being performed; wait for their results. 20 actions in state performing
text: too long for its approval card; shorten it. send whose largest card form exceeds 15000 bytes
message: too long for its approval card; shorten it. connect whose largest card form exceeds 15000 bytes without the link texts
item: the names of its file and chat are too long for its approval card. download whose largest card form exceeds 15000 bytes
The agent has no owner. The person who runs it has to join its control chat with the link the server printed. no approver, --owners absent
The agent has no approving owner. The person who runs it has to restart it with the --owners options it printed. no approver, --owners given

Largest card form (largestCard, encodedLength): the maximum of the creation form, the done form and a failed form with an error of 600 × €, with the action's own decider or the longest current approver name; each form is measured as JSON-escaped UTF-8: ", \, \n, \r, \t 2 bytes, other characters below U+0020 6 bytes.

The link texts of a connect card are its description and welcome lines. These lines, and the input preview lines of a tool-use card in the plugin, are fitted into 15000 bytes minus the largest form without them (Control.refusal, fittedLines). Lines are kept while they fit. The next line is cut to the bytes left and ends in …, and later lines are left out. Both link texts are whole in the tool result.


2. Agent control chat

2.1 Commands and replies

Accepted text (parseCommand, ownerRequest):

message   one line, an optional trailing newline
line      spaces, "/", KEYWORD, PARAMS
KEYWORD   characters up to the first whitespace
PARAMS    the rest, trimmed, split on whitespace
CHAT      @N or #N, 1 to 15 digits
requests
  approve N
  approve CHAT N
  reject N
  reject CHAT N
  receive N
  receive CHAT N
  receive CHAT N all
  receive CHAT off
  forward N
  forward CHAT N
  approve CHAT all
  revoke CHAT
  leave CHAT
  delete CHAT files
  pending
  list
  give CHAT N         in a plugin session group only
  observer #G ID      in a plugin session group only

The server reads commands from members' messages in the main conversation of the control chat (startAgent, Control.onMessage). It answers a command with a reply that quotes it, one command after another, and it runs the expiry check before each command (Control.onMessage, ownerCommand).

Request Condition Reply Code
one-line / text outside the requests any sender Commands: /approve, /reject, /receive, /forward, /revoke, /leave, /delete, /pending, /list. Each card shows its commands. The reply in a plugin session group is in 4.3 commandsReply, unknownCommand, Control.ownerCommand
any request sender not an approver, --owners absent Only owners approve actions. Control.ownerCommand
any request sender not an approver, --owners given Only the owners listed in --owners approve actions. Control.ownerCommand
approve, reject, receive, forward with N action N absent, not pending, or without a card Action N is not pending. Control.ownerCommand
the same with CHAT action N is a connect, or for another chat Action N is not for CHAT. Control.ownerCommand
approve action N is a download Action N is a download: COMMANDS., COMMANDS the card's command line Control.ownerCommand
receive, forward, receive CHAT N all action N is not a download Action N is not a download. Control.ownerCommand
approve, reject, receive, forward accepted none; the card is edited at the outcome; forward posts the file, as a reply to the card when the message with the card as its quote is within 15602 bytes, and the card stays pending Control.ownerCommand, forward
approve CHAT all mode host; nothing is stored Approvals apply in mode requests; this server runs in mode host. Control.ownerCommand
approve CHAT all, receive CHAT N all CHAT unknown or the control chat No chat CHAT. /list shows the agent's chats. Control.approveChat
approve CHAT all accepted; the pending sends of CHAT with a card are approved Approved for KIND NAME (CHAT) by APPROVER. /'revoke CHAT' Control.approveChat
receive CHAT N all accepted; download N is performed, and the other pending downloads of CHAT stay pending Files approved for KIND NAME (CHAT) by APPROVER. /'receive CHAT off' Control.ownerCommand, approveChat
revoke CHAT CHAT unknown, or without a standing approval Messages to CHAT have no standing approval. Control.revoke
revoke CHAT accepted Messages to KIND NAME (CHAT) need approval again. Control.revoke
receive CHAT off CHAT unknown, or without a files approval Files from CHAT have no standing approval. Control.revoke
receive CHAT off accepted Files from KIND NAME (CHAT) need approval again. Control.revoke
leave CHAT CHAT unknown or the control chat No chat CHAT. /list shows the agent's chats. Control.leave
leave CHAT accepted, at once in both modes; the pending actions of CHAT with a card are rejected by the sender Left KIND NAME (CHAT), requested by NAME., or Deleted ... for a contact; logged too Control.leave
delete CHAT files the chat's downloads in memory fail and are cancelled; its other files in status rcvAccepted, rcvTransfer or rcvWarning, such as downloads the core continues after a restart, are cancelled; the folder of CHAT and its forwarded folder are deleted, for a current or a left chat Deleted K files from CHAT, SIZE. (1 file), or No files from CHAT. Control.deleteFiles, AgentTools.deleteChatFiles, receivingFiles
pending no pending action with a card No pending actions. Control.ownerCommand
pending otherwise one line per action: N WHAT expires YYYY-MM-DD HH:MM UTC Control.ownerCommand, pendingLine
list no chats No chats. Control.chatsText
list otherwise one line per chat of the 100 most recent: CHAT KIND NAME, then , approved for this chat by APPROVER, , files approved by APPROVER and , not connected when applicable, cut to 100 bytes with …; then K older chats are not shown. (1 older chat is not shown.) Control.chatsText

KIND is contact, bot, agent, business, group or channel (contactKind, groupKind). WHAT is connect to SUBJECT, send to SUBJECT, download NAME from SUBJECT, delete SUBJECT or leave SUBJECT (summary). SIZE is in bytes, KB, MB or GB, by 1000, with one decimal (sizeText). Names are shown by safeName.

A standing approval is stored in the chat's custom data, simplexMcp for messages and simplexMcpFiles for files, as {approvedBy, approvedById, approvedAt}; it applies in mode requests while member approvedById is an approver (standings, Control.standingApprover).

2.2 Cards

Card text: request lines, then one last line (cardText, requestLines).

Request lines:

Tool First line Further lines
connect I want to connect to SUBJECT, as myself. or , incognito.
done and connected: I connected to ...
done and not connected: I asked to connect to ...
link description, one code span per line
welcome, one code span per line
both cut to fit the card (1.9)
with message: With the message: and its lines
send I want to send a message to SUBJECT:, with , where I am incognito before the colon in incognito chats
done: I sent a message to ...
text, one code span per line
with file: attaching TYPE `PATH`, SIZE
replying to NAME: QUOTE with reply_to, the quote cut to 100 characters
mentioning @A, @'B C' with mention
download I want to download a file from SENDER in KIND NAME (CHAT):, without SENDER in outside groups
done: I downloaded a file from ...
`NAME`, SIZE
an XFTP file: Servers: known., or Servers: `HOST`, `HOST`, unknown: downloading shows them this computer's IP address. (it for one)
leave I want to delete KIND NAME (@N). or I want to leave KIND NAME (#N).
done: I deleted ... or I left ...

SUBJECT is KIND NAME, or an unnamed KIND, followed by (SIMPLEX_NAME) when known (subjectText). For connect, SIMPLEX_NAME is the target when it is a name; for send, the chat's verified SimpleX name.

A card of a send with an image or video file, or of a download of an image or video, is an image or video message. Its image is the file's preview, and its caption is the card text. The preview is resized when it is too large for the card, and the card is text when the preview can't be resized (Control.cardContent, fittedImage).

In a plugin session group, the core can refuse a card with feature not allowed NAME (Control.postCardContent, sessionRefusal, postRefusal, outcome, refusedCardSubject, refusedFeature, featureOff, Actions.runPerform, create, approve):

  • A card refused with feature not allowed Files and media, as when files and media are off in the group's preferences, is posted as text, and its later edits are text.
  • When the core refuses a card for another preference, even after the change to text, the card is not posted. In its place, Claude posts Action N: NAME are off in the group of this session; its owners can turn them on in the group's preferences. An action that waits for approval then fails with the text after Action N: .
  • After the decision, the action stays as it was, and Action N: is replaced by a prefix with the outcome and the card. The outcome card of an action performed in mode host or under a standing approval is posted after the action, and its prefix is Action N was performed; its card was not posted: or Action N failed; its card was not posted: . When the core refuses an edit this way, the prefix is Action N OUTCOME; its card was not updated: , with OUTCOME was performed, failed, was rejected, expired or ended.
  • At a stop, the prefix of a posted or edited card is Action N: .

In serve, an action that waits for approval fails with the core's error, and a refused outcome card or edit is logged.

Last line:

State Condition Last line
pending command line
pending interrupted Cancelled: the server stopped.
performing interrupted DECIDER; interrupted: the server stopped.
done standing Approved for this chat by NAME. /'revoke CHAT'
done DECIDER.
failed DECIDER; failed: `ERROR`.
rejected Rejected by NAME.
expired Expired.
expired ended in the plugin, see 4.3 Ended.

DECIDER is Performed without approval (mode host) in mode host, Approved for this chat by NAME for a standing action, and Approved by NAME otherwise (cardText).

Command lines (commandsLine):

Tool Command line
connect /'approve N' or /'reject N'
send /'approve CHAT N', /'approve CHAT all' or /'reject CHAT N'
download /'receive CHAT N', /'receive CHAT N all', /'forward CHAT N' or /'reject CHAT N', without /'receive CHAT N all' for unknown servers
leave /'approve CHAT N' or /'reject CHAT N'

The app shows /'approve N' as the tappable command /approve N (PLAN, What the owner sees).

An action performed without a card, in mode host or under a standing approval, gets its outcome as a new message; a download without a card gets none (Control.outcome, hasOutcomeCard).

Situation Text Code
send with a refused file; logged too Refused to send `PATH` to KIND NAME (CHAT): private keys and the server's own files are not sent. Control.refusedFile
sndFileError of a sent file; logged too The file `NAME` was not sent to KIND NAME (CHAT): `REASON`. Control.fileNotSent, startAgent
/forward of a file that is not received or not posted Action N: the file was not received: `ERROR`. Control.forward
/forward in a plugin session group, when the core refuses the post with feature not allowed NAME, as for Files and media or Voice messages Action N: NAME are off in the group of this session; its owners can turn them on in the group's preferences. Control.forward, refusedFeature, featureOff
after the reply to /leave CHAT, and after the outcome of a done leave, when the folder of CHAT has files Files from KIND NAME (CHAT) are kept in `FOLDER`: K files, SIZE. /'delete CHAT files' Control.outcome, leave, leftChatFilesNote

2.4 Membership messages

Posted in the chat and logged; in the chat, names are shown by safeName and the --owners ... part is a code span; in the log, names are folded to one line (Control.announce, inLog, inChat).

Situation Text Code
owner joined, --owners absent I'm your agent. I ask here before I connect, send, download a file or leave a chat. (chat only) greeting, Control.ownerJoined
member joined, --owners without a list NAME joined (member ID). Restart the server with --owners ENTRIES Control.observerJoined
start with --owners without a list and humans present A joined (member ID). B joined (member ID). Restart the server with --owners ENTRIES Control.startObserver
a human became owner outside the list NAME (member ID) is now an owner and can't approve actions yet. Restart the server with --owners ENTRIES Control.reportOwnerChanges
a listed owner stopped being a human owner NAME (member ID) is no longer an owner. Restart the server with --owners ENTRIES
none remains: NAME (member ID) is no longer an owner. No owners remain: restart the server with --reset-owners --owners
Control.reportOwnerChanges

ENTRIES: ID:NAME of each human, or of each human owner, joined by commas; an entry with characters other than letters, digits, _ and - is quoted for the shell (entryText, ownersText, restartText).

2.5 Group profile

Field Value Code
display name the agent's display name, updated at start when it differs from the display name in the group's profile read at the start. The other fields of that profile are kept, as in 0.2 Control.load, updateProfile, changeGroupProfile
full name empty createControlChat
description Supervise your AI agent here: approve or reject its connections and messages with one tap. createControlChat
history on createControlChat
command menu /pending "Pending actions"
/list "Chats and approvals"
/leave "Leave a chat", params <chat ID>
updated at start when it differs
controlCommands, Control.load

3. CLI

Binary: simplex-mcp, compiled dist/cli.js (bin). Help text: helpText.

simplex-mcp --help
simplex-mcp serve NAME [options]
simplex-mcp register NAME [options]

The plugin's commands are in 4.7.

NAME: 1 to 32 characters of [a-z0-9] and single hyphens, starting with a letter or digit (validAgentName).

3.1 serve

Option Value Default Rule Code
--data folder ~/.simplex-mcp/NAME resolved to an absolute path; dataGiven is set serveOptions
--display-name text NAME when the user is created must equal validName(text) serveOptions, displayName
--approve requests or host requests serveOptions
--owners absent value, or ID:NAME,... absent the value is absent when the next argument is missing or starts with --; it is split at each comma followed by ID:, so a name may hold commas; entries match ^([1-9]\d*):(.+)$ serveOptions, ownerEntry
--expire hours 23 integer 1 to 23 serveOptions
--stop-wait seconds 10 integer 0 to 60 serveOptions
--reset-owners flag off refused with an --owners list serveOptions
--new-token flag off serveOptions
--port number 5226 integer 1 to 65535 serveOptions
--qr-code small or large small serveOptions

3.2 register

Option Value Default Code
--scope user or local user registerOptions
--data folder ~/.simplex-mcp/NAME registerOptions

Entry (registryEntry):

Field Value
type http
url http://127.0.0.1:PORT/mcp
headersHelper cat DATA/headers.json, Windows type DATA\headers.json, path shell-quoted
timeout (expireHours + 24) × 3600000 + 600000 ms

Server name: simplex-NAME (register).

3.3 Exit codes and messages

Code Message Code location
0 --help text on stdout; a stop after a signal main, serve
2 Usage: simplex-mcp serve NAME [options] or simplex-mcp register NAME [options]. Run simplex-mcp --help. parseCommand
2 NAME: 1 to 32 lowercase letters, digits and single hyphens, starting with a letter or digit. parseCommand
2 OPTION: a value expected. OptionReader.value
2 Unknown option OPTION. Run simplex-mcp --help. unknownOption
2 --display-name: not a valid SimpleX name; try VALID displayName
2 --approve: requests or host expected, got VALUE approveMode
2 --qr-code: small or large expected, got VALUE qrCodeSize
2 --scope: user or local expected, got VALUE scope
2 --owners: ID:NAME expected, got ENTRY ownerEntry
2 --expire: hours from 1 to 23 expected, got VALUE serveOptions, integer
2 --stop-wait: seconds from 0 to 60 expected, got VALUE serveOptions, integer
2 --port: a port from 1 to 65535 expected, got VALUE serveOptions, integer
2 --reset-owners takes --owners without a list: member IDs change in a new agent control chat. serveOptions
2 --owners: member ENTRY is not in the agent control chat. Start with --reset-owners --owners, or use the IDs of current members. Control.startListed
1 Another server uses DATA (PID N). If no server runs, remove DATA/lock. acquireLock, lockedError
1 Port PORT is in use. Start with --port N. listen
1 Agent "NAME" was never started. Start it with: npx -y @simplex-chat/mcp serve NAME register
1 Add this entry under LOCATION in ~/.claude.json: {"simplex-NAME": ENTRY} manualEntryText
1 claude mcp add-json failed: STDERR register
1 simplex-mcp: ERROR for other errors, stop: ERROR for a failed stop top-level catch of main in cli.ts, serve

LOCATION is "mcpServers" for scope user, and "projects" > "PROJECT" > "mcpServers" for scope local (manualEntryText).

3.4 Terminal lines

stdout (log):

Moment Line Code
start SimpleX MCP server VERSION, agent "NAME"
Data folder: DATA
Approval mode: MODE
startServer
control chat created Agent control chat "DISPLAY" created. createControlChat
link opened Join the agent control chat in the SimpleX app. The link works once:
QR code
link
small QR code: If the QR code does not scan, restart with --qr-code large, or paste the link into the app.
role line
Control.openLink
listening Listening on http://127.0.0.1:PORT/mcp startAgent
owner setup done Add the agent to Claude Code:
npx -y @simplex-chat/mcp register NAME [--data DATA]
registerHint
owner joined NAME joined (member ID) and is now an owner. The link is deleted. Control.ownerJoined
listed owners set Owners: ENTRIES. Control.startListed
approvers gone, --owners absent No owners in the agent control chat. noOwners, Control.onEvent, startOwners
control chat lost The agent lost its control chat. Restart the server with --reset-owners. Control.lose
action created Action N: WHAT with , as itself or , incognito for connect and (CHAT) for the other tools Actions.create, summary
counter write or card post failed Action N: failed: ERROR. Actions.post
perform ended, not interrupted by the stop, mode requests Action N approved by NAME: RESULT with RESULT sent., downloaded., deleted., left., connected., connection requested. or failed: ERROR. Actions.runPerform, performedText
perform ended, not interrupted by the stop, mode host Action N: performed without approval (mode host)., or ...; failed: ERROR. performedText
rejected Action N rejected by NAME. Actions.reject
expired Action N expired. Actions.expire
/leave CHAT Left KIND NAME (CHAT), requested by NAME. or Deleted ... Control.leave
refused file, file not sent as in 2.3, names and paths on one line Control.refusedFile, fileNotSent
stop Cancelled K action. or Cancelled K actions. when K > 0
Stopping: sending K cancelled card(s), up to S s. Ctrl-C to stop now. when cards were edited or posted and S > 0
Stopped.
stop in startAgent, waitForCancelledCards
membership messages see 2.4

In the plugin's lines with failed: ERROR., logged for the actions of a session, the last period is added only when ERROR does not end with one (sentence). In serve, a period is added after every ERROR of these lines, and after every REASON of the line of a file not sent, as in 0.2.

stderr: CONTEXT: ERROR from logError, with CONTEXT one of action N, action N card, action N card image, action N file, control chat command, EVENT in the agent control chat, EVENT event, refused file, file not sent, download of file N, file N, moving file N, cancelling file N, resizing PATH, preview, MCP, HTTP request, stop, simplex-mcp. The library's download lines are written to stderr.


4. Claude Code plugin

4.1 Tools in the plugin

Rule Code
The six tools of 1 and reply are registered on the session's McpServer. Claude Code names them mcp__plugin_simplex_simplex__NAME startSession, the PreToolUse matcher of hooks
The four action tools are registered with _meta: {"anthropic/requiresUserInteraction": true} when the option approve is host at the start of the session process startSession, registerTools
pre_tool_use, with input {tool}, answers the PreToolUse hook of type mcp_tool of 4.8. For a tool in the approved tools of the session server's current attachment (4.6), its text is {"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"Approved for this session by NAME in the session's SimpleX group."}}; otherwise it is empty. It sends no request to the service and returns no error, also in a run that is not interactive and with an invalid option. Its description, which Claude sees: Answers the plugin's PreToolUse hook before each tool use: allow for a tool that an admin or owner of the SimpleX group of this session approved for the rest of the session, and nothing otherwise. You never need to call it. hookTool, startSession, ServiceLink.approvedBy, hookOutput
Instructions: those of 1.1, with the display name Claude and the host SimpleX service, followed by the channel instructions of 4.5 channelInstructions, startSession, instructions
send, receive, download, leave and list see only the session's own chats. For another session's chat, send, receive, download and leave return No chat CHAT. list shows the agent's chats. AgentTools.owns, knownChat
At connect, a known chat without an owner becomes the session's chat. connect to a chat of another session returns the tool error The chat of TARGET belongs to another session; an admin or owner of that session's group can give it to this session with /give. AgentTools.ownChat
Actions are numbered from 1 in each session group. The session number is part of the action key, see 1.1 Session constructor, actionKey
Downloads are saved under ROOT/_sessions/ID/files/ the agent of the Session constructor, chatFolder
A run is not interactive when CLAUDE_CODE_SESSION_ATTENDED is 0, which Claude Code sets for the hooks of a run nobody attends, or when CLAUDE_CODE_ENTRYPOINT is sdk-cli, which Claude Code sets for claude -p, or sdk-ts or sdk-py, for the Agent SDK. Such a run has no session. Its session process does not connect to the service, and every tool returns This Claude Code run is not interactive, so it has no SimpleX group; the SimpleX tools work in interactive sessions., even when an option is invalid. Its hooks return {}, and the turn hooks send no request unattendedEntrypoints, interactiveEntrypoint, interactive, unattendedRun, startSession, sessionStart, turn
A run with CLAUDE_CODE_SESSION_ATTENDED 0 and an entrypoint other than those three is, for example, a claude -p run started by a command of a VS Code or desktop-app session. Its SessionStart hook starts the service and sends /title with unattended for its CLAUDE_PID. The session server of that run gets the values of the attended session, 1 and its entrypoint. The service refuses it with status 403 when it registers from that process within 10 s of the mark. The refused server then answers every call with the same text, relays no permission request and registers no more markUnattended, Service.markUnattended, refuseUnattended, ServiceLink.connect, start, permission, call, open

reply (replyTool, AgentTools.reply):

Field Type Range Default Rule
file string 1 character or more required path of a file of this computer
text string 1 to 12000 characters the caption

The file is checked and sent as for send (1.3). The same rules apply to the file types, refused paths, empty files, the size of the message with the caption and the file's preview, and the change check. Without a group, the tool error is reply: this server has no group to reply to.

on reply {file, text?}:
  file checked
  the message with the caption and the file's preview does not fit by fitsMessage:
    tool error "text: too long for a message with this TYPE; shorten it."
  sent at once, without a card, in both modes      -> {item}
  the core refuses it with "feature not allowed NAME", as "Files and media" for the file or "SimpleX links" for a link in the caption:
    tool error "NAME are off in the group of this session; its owners can turn them on in the group's preferences."
  the core refuses it otherwise:
    tool error, the core's text

Sources: AgentTools.reply, sendFile, refusedFeature, featureOff, AgentTools.call, the replyChat of the Session constructor. The core checks the preference at the send, and only owners change it. Claude changes only its own fields of a group's profile, so the owners' preferences stay (Control.load, rename, describe, updateProfile, updateGroupProfile, changeGroupProfile, MainGroup.load). The profile updates are in 4.2 and 4.3.

4.2 Main group

Commands from any member, one line /KEYWORD PARAMS as in 2.1 (MainGroup.command):

Request Condition Reply Code
/sessions the text of the list of sessions, below, fitted to one message with the quote of the command Hub.sessionsText
/join N no session N No session N. /sessions lists the sessions. Hub.join
/join N the sender is a member of its group You are a member of "N · NAME". Hub.join
/join N otherwise: the sender is invited through the Main group, as owner when the sender is an owner of the Main group, else as admin Sent you an invitation to "N · NAME". Hub.join, Session.invite
other one-line / text Unknown command. unknownCommand, MainGroup.command

Posts:

Moment Text Code
the first owner joined I'm Claude. Each Claude Code session has its own group, and you get its invitation here. /sessions lists the sessions; /join N joins the group of session N. greeting, MainGroup.ownerJoined
each joinedGroupMember or connectedToGroupMember of a human who is found among the members read again. For the first owner, it is posted after the greeting NAME joined. They can join the group of any Claude Code session here, prompt Claude and approve its actions. joinRights, MainGroup.handleEvent
the first render of the list of sessions while the group has an owner, so after the greeting; a list 23 hours old, or one whose edit the core refuses with invalidChatItemUpdate or chatItemNotFound the list of sessions, below, with priority: -1. A new list replaces an old one, which is then deleted for everyone; a refused deletion is logged as old list of sessions: ERROR MainGroup.showList, replaceList, postList

The list of sessions (Hub.sessionsText, Hub.showSessions, Session.stateLine):

Part Text Condition
a running session 🔵 N · NAME: waiting for you, K approvals, 1 approval for one K pending cards of the session, without those cancelled by a stop. A tool-use card counts while Claude Code's state is waiting or unknown
🔵 N · NAME: waiting for you in Claude Code no card; attached; state waiting
🟠 N · NAME: working no card; attached; state busy
🟢 N · NAME: idle no card; attached; state idle or shell
▶️ N · NAME: running no card; attached; no record path, no record file, or another state
the other sessions ⚪ Not running: N · NAME, N · NAME, K older sessions, newest first sessions without a card and without an attachment, or all of them while the service stops
no session No sessions.
  • A session is attached while its session server is attached and the service does not stop. Its state is the status of Claude Code's record of the session server's parent, CLAUDE_CONFIG_DIR or ~/.claude, then sessions/PID.json, read every 2 s for each attached session. A record that does not parse keeps the last state read; a path that is not a regular file, such as a FIFO, gives no state. A render waits at most 1 s for a read; a read that takes longer keeps the last state, and no new read of that record starts until it ends (Session.readRecord, recordStatus). A status other than busy, waiting, idle and shell is unknown.
  • The lines of running sessions come by number, then the line of the other sessions. Lines are joined by line breaks.
  • The text fits one message, by fitsMessage. The lines of running sessions are kept whole. The last line keeps the most names, newest first, for which the text, with , K older sessions for the K left out (1 older session for one), still fits. When no name fits, it is ⚪ Not running: K older sessions.
  • Every 2 s, and once at the service's stop before the wait for the cancelled cards, the hub renders the text, and Claude edits the list when the text differs from the text last posted or edited. The first render after a start always edits.
  • A text that the core refuses as too large, errorStore largeMsg, as with more lines of running sessions than one message holds, is logged as list of sessions: ERROR once, and not sent again until the text changes; the list keeps its last text.
  • When the item of a new list can't be saved in the Main group's custom data, the new list is deleted for everyone, the old one stays, and the next render tries again.

The session groups stay as they are when the membership or a role in the Main group is changed, and when the Main group is replaced by a reset of the owners. Members invited through the old Main group keep their roles in the session groups, with the rights of those roles (MainGroup.handleEvent, replace, Session.approves).

Group profile (createMainGroup, MainGroup.load):

Field Value
display name option main_group, followed by - MACHINE when SIMPLEX_MCP_MACHINE is set, updated when it differs
short description Everyone in this group can join the groups of your Claude Code sessions, prompt Claude and approve what it does., set when the group is created
description Everyone in this group can join the groups of your Claude Code sessions, prompt Claude and approve what it does. Invite only people you trust with that., set when the group is created
history on
direct messages on for the role owner
command menu /sessions "Claude Code sessions"
/join "Join the group of a session", params <session number>
custom data {simplexMcpMain: true}, and simplexMcpList: {item, at}, the list of sessions and the time it was posted

Claude updates only the display name and the command menu, starting each time from the group's current profile in the chat database. So the short description, the description and the preferences that owners set stay (MainGroup.load, updateGroupProfile, changeGroupProfile).

The hub's profile Claude posts in the group, with peer type agent (profileName, Hub.open, openCore).

4.3 Session groups

Commands and replies are those of 2.1, from approvers as defined in architecture 8.5, with these changes:

Request Condition Reply Code
any request the sender is not an approver: a moderator, member, author or observer, or User. Control drops a request of User before this check. A moderator, member or author gets the reply of the last row instead none, and nothing is performed Control.onMessage, ownerCommand
/give CHAT N CHAT is not a chat of this session No chat CHAT. /list shows the agent's chats. Control.give
/give CHAT N no session N No session N. /sessions in the Main group lists the sessions. Control.give
/give CHAT N accepted: CHAT's owner is set to session N, and the pending actions of CHAT with a card are rejected by the sender Gave KIND NAME (CHAT) to session N. Control.give
/list, /revoke CHAT, /leave CHAT only the chats of this session, even while the session is closed AgentTools.agentChats, knownChat
/give CHAT N in the control chat of serve any sender the help reply, as in 0.2 Control.ownerCommand, ownerRequest
/observer #G ID #G is not this group #G is not this group. Control.setObserver
/observer #G ID member ID is neither current nor pending, as it is absent, gone, or invited and not joined yet No member ID in this group. Control.setObserver, memberCurrent, memberCurrentOrPending
/observer #G ID ID is Claude, the sender, a relay or a member pending approval or review NAME's role can't be changed. Control.setObserver
/observer #G ID the sender's role is below admin or below the member's role, as SimpleX requires for a role change Your role does not let you change the role of NAME. Control.setObserver, roleRank
/observer #G ID accepted: the member's role is set to observer, and the members are read again. The standing approvals that this member gave are kept in the chat's custom data, and are ignored until the member is an admin or owner again NAME is an observer and can't send messages. Control.setObserver, rightsText, Control.standingApprover
/approve N all action N is not pending or has no card Action N is not pending. Control.ownerCommand
/approve N all action N is not a tool use Action N is not a tool use. Control.ownerCommand
/approve N all accepted: the tool of action N is approved by the sender for the rest of the session, the session's attachments get the approved tools (4.6), and action N is approved as by /approve N Approved `TOOL` for the rest of this session by NAME. /'revoke TOOL' Control.approveTool, Session.sendTools
/revoke TOOL TOOL, of letters, digits, _ and -, is approved Uses of `TOOL` need approval again. Control.revokeTool
/revoke TOOL TOOL is not approved Uses of `TOOL` have no standing approval. Control.revokeTool
/list the chats of 2.1, then one line per approved tool: `TOOL` approved for this session by NAME Control.chatsText, Control.approvedTools
one-line / text outside the requests an admin or owner Unknown command. unknownCommand, Control.ownerCommand
any one-line / text a moderator, member or author. The session replies before Control, and the text is passed to neither Control nor Claude Only admins and owners of this group can send / commands., quoting the message commandsApproversOnly, Session.onMessage, refusesCommand

The requests give CHAT N and observer #G ID of 2.1, approve N all and revoke TOOL are parsed only in a plugin session group (ownerRequest). Approvers are the active members of the session group with the role admin or owner, other than Claude and User, however they joined. An observer can't send, because the core refuses an observer's message (Session.approves, isUser, sessionApproverRoles, Control.approvers, isHuman, isApprover). The core accepts an observer's reaction, and the hub ignores it (Session.onReaction, canSend).

The hub handles other messages by these rules, in arrival order, one at a time (Session.onMessage, prompt, queue, refusesCommand, approves, Control.onMessage):

on a received message in the session group, by its text:
  one line "/KEYWORD ...", the sender neither an admin, an owner nor User
                                                           -> reply "Only admins and owners of this group can send / commands."
  one line "/KEYWORD ..."                                  -> a command, above; from User, ignored
  sender User                                              -> ignored
  other text                                               -> the prompt as sent, after the quote line of a reply (4.5)
the sender's role is the role in the session group of the message's member

The hub handles reactions in the same order as the messages (reactionEmoji, unsupportedReaction, Session.onReaction, prompt, refuseReaction, Hub.onEvent):

on chatItemReaction in the session group, outside a member support scope:
  a removed reaction                                       -> ignored
  the reacting member an observer or a relay               -> ignored
  the reacting member User                                 -> ignored
  the reacted item not a message                           -> ignored
  an emoji of the apps: 👍 👎 😀 😂 😢 ❤ 🚀 ✅             -> the prompt EMOJI, after the quote line of the reacted message (4.5)
  any other reaction, to "This reaction is not supported." -> ignored
  any other reaction, replied before for this member and the reacted message
                                                           -> ignored
  any other reaction                                       -> reply "This reaction is not supported.", quoting the reacted message
on chatItemReaction in the Main group                      -> ignored

A reaction is never a command or an approval: a reaction to a pending card leaves the card pending.

Any member who can send messages in the group can prompt Claude, however they joined: through the Main group, or added to the group directly.

The approved tools of a session are kept in memory, in its Control, with the name and the member ID of the approver. A tool counts as approved only while its approver is an admin or owner of the group, and counts again when that member becomes one again. The hub sends the approved tools to the session's attachments when they change: at /approve N all, at /revoke TOOL, after /observer, and after each membership event of the group, before the rights post. A new attachment gets them at once. The approvals belong to the Claude Code process of the session: they are kept when that process attaches again, as after a failed call, and dropped when /session comes from another process and when the session closes. A process is identified by its ID and its start time, read on Linux and macOS. A /session with a process ID whose start time is unknown, on other systems or after a failed read, counts as another process. While attachments of two processes are open, only those of the process of the last /session get the approved tools; the others get the empty list. They also end when the session's group is lost: deleted, Claude removed, or Claude no longer its owner, found at an event or at a load (Control.approvedTools, endToolApprovals, onEvent, load, lose, Session.onLine, sendTools, endToolApprovals, Hub.onEvent, Service.onSession, onAttach, scheduleIdle, processStart).

The cards are those of 2.2, and two more:

Tool Request lines Command line
mode I want to run in mode host: Claude Code asks you before each of my actions, and they are performed without approval here.
done: I run in mode host: ...
/'approve N' or /'reject N'
permission I want to use `TOOL`: `DESCRIPTION` , then the input preview, one code span per line, cut to fit the card (1.9). When TOOL was approved for the session as the card was created, a last line `TOOL` is approved for this session, and Claude Code still asks for this use. /'approve N', /'approve N all' or /'reject N'; for an approved TOOL, /'approve N' or /'reject N'

mode and permission are exempt from the card size check (Control.refusal, requestLines, commandsLine). In /pending, their WHAT is run in mode MODE and use TOOL (summary). The last line of a mode or permission card is Ended. when the hub ends the card, and Expired. when it expires. The hub ends a permission card at an answer, or at a prompt that is not mid-turn, whose hook started after the card was created, and at the last detach; it ends a mode card at the option requests (Session.requestMode, turn, endPermissions, Service.onAttach, Actions.end, cardText).

Posts:

Poster Text Code
Claude the opening message of a turn: at a prompt that starts a turn, that User posts or that matches a member's prompt, an empty live message with priority -1, quoting the member's prompt or reacted message when the quote fits. It is kept before User's post and sent after it, so a post of the turn that arrives meanwhile waits for it. The first post of the turn whose hook started no earlier than the prompt's hook fills it: the start of a step, the first text, the first part of an answer, or the end line of a blank answer. A post that a group preference refuses fills it with the text in its place, or with ⏹️ Stopped when that update fails too. When its update fails for another reason, as after its deletion, the hub drops it, logs the failure, updates it with ⏹️ Stopped and liveMessage: false, and sends that post as a new message. A prompt that starts the next turn bounds it, so posts of hooks that started from then on leave it. An opening message that no post filled is updated with ⏹️ Stopped and liveMessage: false at the first answer whose hook started no earlier than that bound, or than its own start while it has no bound, at the last detach, at the hub's stop, and 23 hours after its send by the wall clock Session.turn, openTurn, boundOpenings, takeOpening, closeOpenings, startLine, fill, expireLive, quoteOf
Claude text of a /turn request, a batch of Claude's text from the MessageDisplay hook. The hub applies the batches of a message in index order, in one queue with the starts of steps, and sends its first text that is not blank as a live message with priority -1, filling the opening message. It updates the message at most once per 3 s with the text applied so far, and at once with the whole text at the final batch, still live. The message is updated with liveMessage: false 10 s after the final batch, before the next step or the first batch of the next text, or at Stop with the end line when the text is the answer's message. A text that outgrows a message is finalized at the part that fits, measured by textParts, and continues in a new live message. A batch of a message that ended is dropped, and so is the first batch of a message whose hook started before the last answer's hook. At a prompt that starts a turn, at the last detach and at the hub's stop, each live text is finalized with its own text, and so is a live text 23 hours after the send of its message, by the wall clock. For a text that fills the opening message, that send is the opening message's textUpdateMs, textEndMs, Session.text, queueLive, addBatch, completeText, endComplete, showText, updateText, endPart, endText, endTexts, step, expireLive
Claude the final answer of each turn. The newest text whose first batch's hook started after the turn's start and before the Stop hook, live or among the last 20 ended that have a message or were refused, is the answer's message when its trimmed text starts the trimmed answer. Its message is then finalized with the answer after the text's earlier parts and the end line, when the text was not refused; parts that the message can't hold are sent as new messages, with priority -1, and priority 1 for the last, or the update has priority 1 when it holds the end line. Without such a text, the answer is sent in parts with the end line, with priority -1, and priority 1 for the last, the first part filling the opening message, or, without it or after a failed update of it, quoting the turn's prompt from the group, chosen by the hub from the turn records below, when the quote fits with the answer's first character. A changed short description is set after the answer Session.turn, turnQuote, answer, postAnswer, claim, endText, endPart, postRefusal, post
Claude the end line of a non-blank answer: !- Done in FIGURES!, appended to the answer's last part after a line break. When the last part with the line does not fit one message, measured by textParts, the last part is cut before its last N + 1 characters, N the line's length, and those characters start a new last part with the line. The message that ends with the line gets priority 1: in its send, or as priority: 1 in the UpdatedMessage of the update that adds the line, sent with /_update item because apiUpdateChatItem takes no priority. The core derives the parser of UpdatedMessage with defaultJSON, aeson's default options with omitNothingFields, which ignore an unknown key, so a core without update priority keeps the message's priority. FIGURES is the request's usage, such as 2 min 51 s · 16K output tokens · 673K tokens in context. Without usage it is DURATION, from the newest turn record not after the Stop hook whose prompt started a turn to the Stop hook, in the format of the step lines; without both the line is !- Done!. The windows of the newest limits whose resetsAt has not passed follow, as · 5 h: N% and · week: N%, with N rounded down. The machine's state follows, read by the service when the Stop request is handled: · RAM SIZE free and · disk SIZE free of the data root, each followed by ❗️ (U+2757 U+FE0F) when low, as machineParts makes them. ❗️ is not an ASCII !, so the core's parser of !- TEXT! (styledP in Markdown.hs) ends the small-print span only at the line's last !. A blank answer adds no line, and an empty opening message is finalized with the end line's text. A refused answer gets the end line after its refusal text, which fills the opening message or is posted, with priority 1. A refused streamed text and a refusal whose update of the opening message fails get no end line Session.turn, answer, postAnswer, claim, endPart, fill, updateText, updateItem, postRefusal, turnStart, endLine, withLine, small, Hub.machine, limitParts, machineState, machineParts, duration
Claude the lines of switches, before the other posts of the request, with priority -1: !- Model changed to MODEL! for a request with switched whose model differs from the shown model, and !- Effort changed to LEVEL! for an effort level that differs from a known shown level. A value older than the one taken last gets no line, as for the description, and so does a hook's effort level once the status line reports. A text with ! is posted without the small marks Session.turn, newer, small
Claude Session N is not running., as a reply to a prompt, or to the reacted message of a reaction, when the session is not attached at the prompt's delivery. The hub delivers the prompt after the earlier prompts and after the prompt's own file. In the first 30 s after the service's start, the reply is posted only when the session does not attach by their end Session.onMessage, onReaction, deliver, Hub.open
Claude The file of this message was not received: ERROR, as a reply to a prompt whose file was not received, see 4.5 Session.deliver, receive
Claude the reply to the one-line / texts of the rules above, quoting the message commandsApproversOnly, Session.onMessage
Claude This reaction is not supported., as a reply to the reacted message of a reaction other than the apps' eight emoji, after the earlier prompts. The session gets nothing for it. The reply is posted once for each member and reacted message while the service runs, and never for a reaction to this reply reactionEmoji, unsupportedReaction, Session.refusedReactions, onReaction, refuseReaction
Claude note of a /turn request, a line about one of Claude Code's own prompts, without a quote, with priority -1, before the other posts of the request. See the hook's notes below Session.turn, recordKind, noteOf, taskNote, teammateNote, idleNotification, peerName, shortened
Claude note of a PostCompact request, ⚙️ Context summarised automatically: PRE → POST tokens, or on request for a summary after /compact, without a quote, with priority -1. A group preference never refuses it: it has no SimpleX link, file, voice message or report Session.turn, compactionNote, prohibitedGroupContent in Internal.hs
Claude step of a /turn request, the line of a tool use. At the step's start, its text is sent as a live message with priority -1. At its end, that message is updated with the final text and liveMessage: false. An end that arrives before its start is sent as a message with priority -1, and the hub then posts nothing for the start. At an answer or a prompt that is not mid-turn, the line of each step without an end whose hook started before that request's hook is updated with its own text and liveMessage: false; at the last detach and at the hub's stop, the line of every step without an end is. The hub then posts nothing for the step's later end. The hub keeps the IDs of the last 100 finished steps. A line still live 23 hours after the send of its start, by the wall clock, is updated with its own text and liveMessage: false, and the step's later end is sent as a new message with priority -1. For a line that fills the opening message, that send is the opening message's. The hub checks the ages every minute while a step, an opening message or a text is live, and before each step. For a start that the core refuses or that fails, the hub posts nothing at its end; a failed send and a failed update are logged. The hub's stop waits for the updates in progress liveLineMs, stepCheckMs, Session.turn, endSteps, endLive, step, startLine, endStep, expireLive, watchLive, remember, Hub.stop, Service.onAttach, stepOf, stepText, displayPath, duration
User each prompt typed in the terminal, also one typed during a turn, in parts. A prompt with typed: false is left out, such as a notification of a background task. A request without typed, from an older plugin, is posted as typed. Blank prompts, prompts made only of this server's channel tags, the prompts pushed from the group and one-line / commands are left out too. User posts in the group that is marked with the session's number Session.turn, User.post
Claude a text in place of an answer, a note, the line of a step or a terminal prompt that the core refuses with feature not allowed NAME, as SimpleX links for a SimpleX link. The text for an answer is Claude's answer was not posted: NAME are off in the group of this session; its owners can turn them on in the group's preferences., quoting the turn's prompt as the answer would. A note, or the line of a step, is replaced by Claude's note was not posted: and the same preference text. A text of Claude whose send or update is refused gets Claude's text was not posted: and the same preference text, once; its message is finalized with the text accepted last, and its later batches are dropped. Such a text, also one that outgrows a message, ends at once, and an update scheduled before its end is skipped. At Stop it counts as the answer's message when its trimmed text starts the trimmed answer, so the answer is not posted again. When a refused post of Claude would fill the turn's opening message, its text in place fills the opening message, updated with liveMessage: false, and is not posted separately. A terminal prompt is replaced by User's prompt was not posted: NAME are not allowed for User in the group of this session; its owners can allow them in the group's preferences., even while NAME is on only for roles above that of User. Claude is an owner of the group, so its answers and notes get only the texts with are off. The turn goes on Session.turn, answer, postAnswer, step, startLine, fill, refused, updateText, refuseText, claim, postRefusal, notAllowedForUser, refusedFeature, featureOff
Claude files sent by reply, at once AgentTools.reply, sendFile, the replyChat of the Session constructor
Claude the rights of the member's role, below. They are posted once for each join and each role change of a member other than User, at its joinedGroupMember, connectedToGroupMember or memberRole Session.announceRights, Hub.onEvent, approverRights, senderRights, observerRights, sessionApproverRoles, canSend, rightsText

Rights posts, by the member's role in the session group:

Role Post
owner NAME is an owner and can send prompts to Claude and the group's commands, and approve tool use.
admin NAME is an admin and can send prompts to Claude and the group's commands, and approve tool use. You can change role to observer to stop it: /'observer #G ID'
moderator, member, author NAME is a member and can send prompts to Claude; the group's commands and approvals need the role admin or owner. You can change role to observer to stop it: /'observer #G ID', with a moderator or an author for those roles
observer NAME is an observer and can't send messages.

#G is the session group, and ID is the member. The core raises no memberRole event for a role change that Claude makes itself, with /observer. The reply to /observer is the observer's post instead.

Parts (textParts, fitsMessage): the hub cuts the text into the longest runs of whole characters that fitsMessage accepts as one message. fitsMessage is the measure of send in 1.3, in UTF-8 bytes. The first part is measured with its quote. The hub puts up to 14962 bytes of text into a part without a quote: 14962 Latin, 7481 Cyrillic or 4987 CJK characters, fewer for characters escaped in JSON.

Claude can quote a message in its answer and its replies. When the core refuses such a post with errorStore invalidQuote or chatItemNotFound, as for a deleted prompt, or with largeMsg, as for a reply that quotes a message near the size limit, the post is sent again without the quote (Session.post, isRefusedQuote).

Turn records, added at a /turn with prompt, are read and changed before the first await of each /turn (Session.turns, turn, turnQuote):

on /turn {at, prompt, midTurn}:
  item = oldest pushed prompt that prompt contains in a channel tag of this server,
         or that equals prompt and was pushed in the last 60 s; else null
  turns += {at, item}, unless at is below answeredAt, or midTurn is true and nothing matched
  the matched pushed prompts are removed
on /turn {at, answer}, also an empty answer:
  earlier = turns with at below the answer's at
  earlier not empty:
    quote = the item of the newest of earlier; null gives no quote
    turns = turns without earlier
  earlier empty:
    quote = the oldest pushed prompt not quoted yet and pushed at or after answeredAt, marked quoted; it stays in pushed for its prompt
  answeredAt = max(answeredAt, at)
at = performance.timeOrigin of the hook process; absent: Infinity for an answer's quote, now otherwise

Group profile (Hub.createSessionGroup, Control.load, describe, updateProfile):

Field Value
display name N · NAME, folded to a valid display name, renamed at a new title
description The Claude Code session N. Members send it prompts; admins and owners also send the group's commands and approve tool use., set only when the group is created
short description MODEL · effort LEVEL, the parts known so far
history on
direct messages off
command menu as in 2.5
chat layout terminal, which the apps name Flat, set only when the group is created
members Claude, the members invited through the Main group, the members others added directly, User
peer types Claude agent; User human, set at each service start (User.open, updatedUser). A member who joined while User had agent, as in 0.3.0, gets human with User's next post in the group, with the event updated profile: the core sends a member's profile to a group before the next message after a change of its name, full name, short description, description, image or peer type

Claude makes the profile updates one at a time. It starts each from the group's current profile in the chat database and changes only the display name, the short description or the command menu. So a rename and a model change that overlap both stay.

The hub takes the model and the effort level of a /turn only when its at is not older than the at of the value it took last. It keeps the two times apart, one for the model and one for the effort level. The model of a /title comes with the at of its SessionStart hook, as described in 4.6. A request without at counts as the current time. So when a Stop request that waited for its transcript entry arrives after a later model switch, the model of the switch stays (Session.turn, newer). The model of a request with an answer that equals the shown model without a final [1m] counts as the shown model, because the transcript names the 1M context variant without that suffix (Session.turn).

After the first request with statusLine in a session, the hub takes the effort level only from requests with statusLine. The hooks send the level of the turn, which is xhigh after ultrathink and can be a skill's or the prompt's own level, while the status line command sends the session's level. So the level of one turn posts no line once the status line reports (Session.turn).

The hub keeps the limits of the request whose at is not older than that of the limits it keeps, in memory, for the end line (Session.turn, endLine).

4.4 Tool results in the plugin

Refusals of a new action, first match, in place of those of 1.9:

Text Condition Code
The SimpleX service is stopping. the service stops hubTexts
The group of this session is lost. Start a new Claude Code session. the session group was deleted, Claude was removed from it or lost its owner role hubTexts, losesControl, isLost
20 actions are pending; wait for the approvers' decisions. 20 actions of the session in state pending hubTexts, Actions.create
the texts of 1.9 for 20 actions being performed and for the card size as in 1.9, with the actions counted per session Actions.create
The group of this session has no admin or owner to approve actions. Members of the Main group join it by /join N there; without members, run npx -y @simplex-chat/mcp@VERSION link in a terminal., with VERSION the plugin's version the session group has no approver noSessionApprover, Control.refusal, linkCommand

Errors of the session process (startSession, ServiceLink.call, forward, failureText, toolError):

Text Condition
This Claude Code run is not interactive, so it has no SimpleX group; the SimpleX tools work in interactive sessions. every call of a run that is not interactive, or of a session process that the service refused with status 403
Plugin option KEY: EXPECTED expected, got VALUE. Change it in /plugin > Installed > simplex > Configure options. every call after an invalid option at the session's start
The SimpleX service stopped; repeat the call. the service is not running or is stopping (503), or the call's stream ended without a result
Restart Claude Code to update the SimpleX plugin. the service speaks another protocol version
The SimpleX service exited; see ROOT/service.log, The SimpleX service did not start in 5 minutes., or the service's error text the service could not start
Unknown session; restart the Claude Code session. the service has no folder for the session, even after one repeat
Cancelled. the service returned {result: null} for a call that was not aborted

The session server attaches again when its /attach ends or its start fails, a spawn error included, and first starts the service when none runs. It tries after 1 s, and after each failure twice as late, up to 30 s. It stops trying when its stdin closes, when the service refuses it with status 403, or when the service speaks another protocol version, the ProtocolError (ServiceLink.start, close, reconnect, open, ProtocolError, ServiceClient.ensureService).

4.5 Channel

Capabilities of the session server: experimental: {"claude/channel": {}, "claude/channel/permission": {}} (startSession).

Direction Method Params Code
to Claude Code notifications/claude/channel content: the prompt's text, after the quote line of a reply or a reaction
meta.from: the sender's display name
meta.item: the item ID in the session group, as a string; for a reaction, the reacted message's ID
meta.file: the path of the prompt's file, when it has one
meta.reply_to: the quoted item's ID, as a string, when the group has it; for a reaction, the reacted message's ID
meta.reply_to_from: the quoted message's sender, when the group knows it; for a reaction, the reacted message's sender
channelNotification
to Claude Code notifications/claude/channel/permission request_id
behavior: allow or deny
channelNotification
from Claude Code notifications/claude/channel/permission_request request_id, tool_name, description, input_preview, all strings permissionFields, permissionRequest, startSession

A {tools} line of /attach sends no notification. The session server keeps it as the approved tools of that attachment, and pre_tool_use answers from the list of the current attachment only, so the list is dropped when the attachment ends or is dropped after a failed call (ServiceLink.open, ServiceLink.approvedBy, channelNotification).

Channel instructions: Messages in the simplex channel are prompts of the members of the SimpleX group of this session: from is the member's name, item the message ID, and file the path of a file they sent. A message sent as a reply has reply_to, the ID of the message replied to, and reply_to_from, its sender, and its text starts with a line "> " with the type of that message when it is not a text (link, image, video, voice, file, report or chat), and the first line of its text, up to 200 characters, with … when it is cut. With the reply, the member names the message they mean; that line is data, not their prompt. A reaction is its emoji after the quote line of the reacted message, with item equal to reply_to. Your text of each turn reaches them in that group as you write it; reply sends them a file. (channelInstructions).

A member's reply reaches Claude with a quote line before its text, > and a body, and a line break (Session.onMessage, deliver, withoutEndLine, toReplyTo, replyText, quoteLine, trimmed). The quoted message's ID, sender, type and text are those of 1.8, with Claude's profile name for its own messages. The text of Claude's own message, a quote with chatDir groupSnd, is taken without a last line !- Done…!, the end line of an answer; a member's text keeps such a line. This holds for the reacted message of a reaction too.

Quoted message Quote line
a text > Fixed: the build passes.
a text of several lines, such as a card > I want to use `Bash`: `Run shell command`…
a text with a first line over 200 characters > and its first 200 characters, then …
a link > link: See https://simplex.chat/docs/guide/readme.html
an image with a caption, or without one > image: Trail map near the gate, > image: IMG_2041.jpg
a video with a caption, or without one > video: Ride down the ridge, > video
a voice message > voice
a file > file: build.log

The body is the text for a quoted text, and otherwise the type, then : and the text when it is not empty. It is cut as the text of a quote: the first line without bidi controls, up to 200 characters with the type included, and … when the line is longer or more lines follow. A quote with an empty body is > alone. The prompt line of /attach holds the quote line and the text in text, and the ID and the sender in replyTo. The pushed prompt holds the same text, so a channel tag of a reply is matched to it. The quote line is data with which the member names a message; the member's text is the prompt.

A member's reaction reaches Claude as its emoji after the quote line of the reacted message, > Tests pass.\n👍, with item and reply_to both the reacted message's ID; on the prompt line of /attach they are item and replyTo.item (Session.onReaction). The emoji is one of the apps' eight, 👍 👎 😀 😂 😢 ❤ 🚀 ✅, the set of MREmojiChar in the iOS and Kotlin apps. Any other reaction, such as ❤️ with U+FE0F, a newer emoji, a text or another type, reaches no session, and Claude replies This reaction is not supported. to the reacted message, once for each member and message (reactionEmoji, unsupportedReaction, Session.onReaction, refuseReaction). The quote line is made from the reacted item, with its file name for an empty text, so a video or a voice message without text is quoted with its file name, such as > video: ride.mp4. The reacted message's own file is not received. The answer of the reaction's turn quotes the reacted message, Claude's own messages included (Session.answer).

The session server negotiates the protocol revision 2025-11-25 and answers server/discover with Method not found, as McpServer of the SDK 2.3.1 does by default. Claude Code 2.1.319 registers no channel for a server that negotiates the modern revision 2026-07-28. A unit test of the session server checks both answers (session.test.ts).

The prompts of a session, from the members of 4.3, are delivered one at a time, in arrival order (Session.onMessage, queue, deliver). While a session is attached, a prompt's file is received without a card, with relays approved, into ROOT/_sessions/ID/files/group/<file ID><extension>. The prompt is pushed after rcvFileComplete. After rcvFileError, a failed receive or 10 minutes, it is pushed without file. The next prompt waits until then (Session.deliver, receive, fileDone). Pushed prompts are kept until they are matched by a turn's prompt, at most 20 (maxPushed, Session.turn, deliver, turnQuote). Each channel tag of a turn's prompt matches one pushed prompt, the oldest with its item and text that no earlier tag matched, so two equal reactions to one message are matched in their own turns (Session.pushedIn).

4.6 Socket protocol

The service speaks HTTP/1.1 over ROOT/service.sock, the fallback path or the Windows pipe, with protocol version 1. Every request is sent with the header Authorization: Bearer TOKEN, and bodies are JSON. Streamed replies are NDJSON, with the content type application/x-ndjson. Errors are {"error": TEXT} with a status other than 200. Types: protocol.ts. Routes: Service.routes. Only /title, /link and /reset-owners return a Main group link. /reset-owners returns the link of the new group.

Route Request Reply Code
POST /session {id, pid?, project, name?, config: {mainGroup, approve, expireHours}, record?}, pid the session server's parent process, record the absolute path of Claude Code's record of that process, which the session's line in the list of sessions reads {number, displayName, version, protocol, owner: {owners}}. For a pid marked unattended, the reply is status 403, see below. The mark is checked before and after the wait for the title of pid Service.onSession, refuseUnattended
POST /title {id, pid?, at?, name?, project, model?, config, unattended?}, pid from CLAUDE_PID, at the performance.timeOrigin of the SessionStart hook {mainGroup, owner: {owners, link?}, version, protocol}, after the title is applied, or at once for a held title. With unattended: true, the reply comes at once, and no session is opened. Marks 10 s old and older are removed, pid is marked, and a server's wait for its title ends Service.onTitle, markUnattended, applyTitle
POST /attach {id, pid?}, pid the session server's parent process a stream held open: the first line {version, protocol}, then {prompt: {text, from, item, file?, replyTo?: {item?, from?}}}, {permission} and {tools} lines. tools is the full list of the session's approved tools, [{tool, approvedBy}], sent when it changes and to each new attachment while it is not empty (4.3). An attachment whose pid is not the one of the session's last /session gets {tools: []} in place of each {tools} line Service.onAttach, AttachLine, ApprovedTool, AttachRequest, Session.onLine, sendTools
POST /call {id, tool, input} lines {progress: TEXT}, then one line {result: CallToolResult or null}. The call is aborted when the request is closed Service.onCall
POST /permission {id, requestId, toolName, description, inputPreview} {} after the card's action is created Service.routes
POST /turn {id, pid?, at?, prompt?, typed?, note?, midTurn?, answer?, model?, switched?, effort?, step?, text?, usage?, limits?, statusLine?}, at the time the hook started, typed whether a person typed the prompt, note the line Claude posts about one of Claude Code's own prompts or a summary of the session's context, midTurn whether Claude Code added the prompt to a running turn, switched whether the model comes from PostModelSwitch, step {id, text, end?} the line of a tool use, with end at the tool use's end, text {message, index, final, delta} a batch of Claude's text, usage the usage text of the Stop hook's turn, limits {fiveHour?, week?} of the status line command, each {percent, resetsAt} with resetsAt in Unix seconds, statusLine whether the status line command sends the request {} after the posts; for text, once the batch is queued Service.routes, TurnRequest, Limits
GET /status none {version, protocol, mainGroup, owner: {owners}, sessions: [{number, name, attached}]}, with the open sessions Service.status
GET /link none {owners, link?}, the link while the Main group has no owner Service.routes, Hub.owner
POST /reset-owners none {link}, the link of the new Main group. The group is replaced at once, even while owners exist Service.routes, Hub.resetOwners
POST /stop none {} after the stop sequence. The process exits after the reply Service.routes
Status Error Condition
401 Unauthorized token missing or wrong
404 Not found other method or path
400 Invalid JSON body not JSON
400 Not a Claude Code session ID: ID a session route with an ID that is not a UUID
400 Invalid config. /session or /title whose config has an invalid mainGroup, approve or expireHours
403 The SessionStart hook of this process marked its run unattended. /session from a process marked unattended in the last 10 s
409 Unknown session; restart the Claude Code session. /attach, /call, /permission or /turn for an ID without a folder
413 Body too large body over 1 MiB
503 The SimpleX service is stopping. a session route while the service stops
500 the error message any other error, a refused permission action included

Session routes are /session, /title, /attach, /call, /permission and /turn (Service.entry, refuseWhenStopping, folder). Their ID is that of a session, or an alias of one (Service.canonical, resolve, attachedSession, processSession, alias):

attached(pid) = the entry whose session server sent that pid and is attached
on /session, /title or /turn with id, pid:
  alias of id                                    -> that session
  a folder with session.json for id:
    /title or /turn, attached(pid)               -> that session, without an alias
    else                                         -> id
  pid absent                                     -> id
  /session, session of pid unknown: wait up to 10 s for a /title with that pid
  session of pid = attached(pid)
                ?? an entry whose session server sent that pid, seen in the last 10 s
                ?? the session of the /title with that pid in the last 10 s
  session of pid ?? id; a session other than id records id as an alias, in aliases of its session.json
on /attach, /call or /permission with id:        alias of id ?? id
on /title with id, pid: no alias, no session.json for id, session of pid unknown or a held title of pid:
  held; the title of pid = id, its name; the reply at once
  the title resolves as above once a /session with that pid arrives, or after 10 s, while the service runs
on /session that creates the session of a held title: the title's name
a new session.json:                              the aliases that already point to its ID
on a service stop:                               the held title requests, with their at, into ROOT/titles.json
on the next start:                               each one taken as a new /title

/session and /title without unattended apply config to the hub (Hub.configure, Service.onSession, onTitle, applyTitle):

  • The hub sets the expiry of all sessions from expireHours.
  • The hub renames the Main group when mainGroup differs.

/session requests the session's mode (Session.requestMode, askMode, setMode, declineHost, Hub.onEvent, the Session constructor):

  • requests applies at once. The hub ends a pending mode card and clears hostDeclined.
  • For host, the hub posts the mode card when the group has an approver and hostDeclined is unset. It posts the card at once, or after the next membership event of the group.
  • When the mode card is rejected, the hub sets hostDeclined in session.json.
  • The hub keeps the mode of an approved card, and a later requests, as mode in the session group's custom data. The session reads it when it opens.

/title opens or creates the session, and renames it when the name is not blank. It passes model to turn with the request's at, the start time of the SessionStart hook. So the model of a hook that started later, during the wait of a held title, stays. For a held title, /title replies at once. The service then opens or creates the session, renames it and passes model when the server of that process registers, or after 10 s, while the service runs (Service.onTitle, applyTitle, processEvent). A /title without at, from an older plugin, counts as the current time.

4.7 Plugin commands

Command Run by Output
simplex-mcp session .mcp.json MCP over stdio
simplex-mcp service spawnService, through the launcher node -e LAUNCHER COMMAND ARGS, which spawns the service with fd 1, 2 and 3 of its own and exits at once, so the service is no descendant of the hook or session process. The launcher writes error: TEXT when the spawn fails (launcher, spawnService) the ready line ready, running or error: TEXT on fd SIMPLEX_MCP_READY_FD, or on stdout when it is unset. The line is dropped when its reader is gone, and the service keeps running (readyChannel, writeReady). If another running process holds ROOT/service.lock, the service checks the lock and the socket up to 150 times, 100 ms apart. It starts again once the lock is released, and its ready line is running once the socket answers. The log is written to stdout and stderr
simplex-mcp hook session-start SessionStart hook one JSON line, see 4.8
simplex-mcp hook turn UserPromptSubmit, Stop, PostModelSwitch, PreToolUse, PostToolUse, PostToolUseFailure and PostCompact hooks {}. A prompt or an answer over 250,000 characters is cut there and ends with … (maxText, cut). The Stop hook sends the model of its answer and the usage of its turn, read from the transcript, and the PostModelSwitch hook sends its model with switched, see 4.8 (turn, eventFields, answerRecord, findInTranscript, readTail, lastAnswer, turnUsage, usageOf). The UserPromptSubmit hook sends typed, note and midTurn, read from the prompt's record in the transcript (turn, promptKind). The tool hooks send step, see 4.8, and nothing for a tool use of a subagent or of this plugin, or without tool_use_id or tool_name (turn, eventFields, stepOf). The PostCompact hook sends note from the compaction's boundary in the transcript, and nothing for a subagent's compaction (eventFields, compactionNote, flow 35)
node dist/display.js MessageDisplay hook {}, after POST /turn with text, see 4.8
node ROOT/status-line.js Claude Code's status line, with the person's statusLine setting the status line, and then POST /turn with effort and limits, see 4.8
simplex-mcp link people with owners, Owners of "MAIN": A, B. To replace them, run npx -y @simplex-chat/mcp@VERSION reset-owners in a terminal. When the service reports neither owners nor a link, The Main group has no link. Run npx -y @simplex-chat/mcp@VERSION reset-owners in a terminal. Otherwise, on a terminal, Join "MAIN" in the SimpleX app. The link works once:, a QR code and the link, and elsewhere Run npx -y @simplex-chat/mcp@VERSION link in a terminal to see the link to "MAIN".
simplex-mcp reset-owners people after POST /reset-owners of 4.6, on a terminal, "MAIN" was replaced. Join the new one in the SimpleX app. The link works once:, a QR code and the link, and elsewhere "MAIN" was replaced. Run npx -y @simplex-chat/mcp@VERSION link in a terminal to see the link to the new one.

VERSION is the version of the package that prints the text (linkCommand, resetCommand).

Environment:

  • SIMPLEX_MCP_HOME: ROOT.
  • CLAUDE_CODE_SESSION_ID and CLAUDE_PROJECT_DIR: the session.
  • CLAUDE_PID: the Claude Code process of a hook.
  • CLAUDE_CODE_ENTRYPOINT and CLAUDE_CODE_SESSION_ATTENDED: a run that is not interactive, as in 4.1. The session process and the hooks read both.
  • CLAUDE_PLUGIN_OPTION_MAIN_GROUP, CLAUDE_PLUGIN_OPTION_APPROVE and CLAUDE_PLUGIN_OPTION_EXPIRE_HOURS: the options.
  • SIMPLEX_MCP_MACHINE: the machine part of the Main group's name, see 4.8.
  • SIMPLEX_MCP_READY_FD: the fd of the service's ready line.

The service is spawned with the variables of the spawning process whose names match, case-insensitively, PATH, PATHEXT, HOME, USERPROFILE, HOMEDRIVE, HOMEPATH, TMPDIR, TMP, TEMP, XDG_CACHE_HOME, LOCALAPPDATA, APPDATA, SYSTEMROOT, SYSTEMDRIVE, WINDIR, COMSPEC, LANG, LC_*, LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, HTTP_PROXY, HTTPS_PROXY, NO_PROXY, NODE_USE_ENV_PROXY, NODE_EXTRA_CA_CERTS, NODE_OPTIONS, SSL_CERT_FILE, SSL_CERT_DIR, SIMPLEX_* and CLAUDE_PLUGIN_OPTION_* (serviceVariables, spawnService).

Code Message Code location
0 the hooks, even after errors, link and reset-owners, and the service after a stop or with running sessionStart, turn, runService
2 simplex-mcp session runs from the Claude Code plugin. startSession
2 Not a Claude Code session ID: ID startSession
1 Restart Claude Code to update the SimpleX plugin., or a spawn error, from link and reset-owners ServiceClient.ensureService, spawnService, firstLine
1 a failed service start, with the ready line error: TEXT. The line is error: Another service uses ROOT (PID N). If no service runs, remove ROOT/service.lock. when the lock's holder neither releases it nor answers in 150 checks runService, lockHolder, lockedError
1 stop: ERROR for a failed stop after a signal runService

The service's stdout and stderr are written to service.log (spawnService). The log is emptied when it is over 10 MB, checked at each spawn and every hour while the service runs (trimLog, openLog, Service.start). stdout lines:

Moment Line Code
start SimpleX MCP service VERSION, data folder ROOT runService
Main group created Main group "NAME" created. createMainGroup
link opened Main group link created. Whoever joins by it first becomes an owner of "NAME". MainGroup.openLink
no owners, members present No owners in the Main group. noOwners, MainGroup.start, handleEvent
owner joined NAME joined (member ID) and is now an owner. The link is deleted. MainGroup.ownerJoined
Main group lost The Main group is lost. Run npx -y @simplex-chat/mcp@VERSION reset-owners in a terminal. MainGroup.lose
session group created Group "N · NAME" of session N created. Hub.createSessionGroup
session group lost The group "N · NAME" is lost. Control.lose
actions as in 3.4, with of session N after Action N, and allowed. for a tool use Actions.create, performedText
stop Cancelled K action(s)., Stopping: sending K cancelled card(s), up to 10 s. Ctrl-C to stop now., Stopped. Service.shutdown, waitForCancelledCards

stderr: CONTEXT: ERROR from logError, with CONTEXT among Main group command, EVENT in the Main group, EVENT in the group of session N, prompt of session N, invitation to session N, User, User in session N, group of session N, session N, owner of CHAT, mode host of session N, title, ROOT/_sessions/ID/session.json, ROOT/titles.json, ROOT/service.log, METHOD PATH and those of 3.4. Session processes and hooks write to their own stderr (startSession, ServiceLink.start, markUnattended, turn):

  • A session process writes SimpleX service: ERROR, SimpleX channel: ERROR and permission relay: ERROR.
  • The SessionStart hook of an unattended run writes SimpleX MCP session start: ERROR, and the turn hook SimpleX MCP turn: ERROR.

4.8 Plugin options, files and hook output

userConfig of .claude-plugin/plugin.json, read by readConfig:

Key Variable Type Default Valid Error
main_group CLAUDE_PLUGIN_OPTION_MAIN_GROUP string Claude Control equal to validName(value) a valid SimpleX name, such as VALID expected or a valid SimpleX name expected
approve CLAUDE_PLUGIN_OPTION_APPROVE string requests requests, host requests or host expected
expire_hours CLAUDE_PLUGIN_OPTION_EXPIRE_HOURS number 23 digits only, 1 to 23 hours from 1 to 23 expected

The default is used for a missing or blank variable (readConfig, mainGroup, approve, expireHours).

SIMPLEX_MCP_MACHINE, set in the environment of a machine or container and not blank, adds - MACHINE to the name of main_group (readConfig, withMachine). Its errors:

  • MACHINE not equal to validName(MACHINE): SIMPLEX_MCP_MACHINE: a valid SimpleX name, such as VALID expected, got MACHINE. Change it in the environment of this machine., or a valid SimpleX name expected when VALID is empty.
  • the full name not equal to its validName, over 50 characters or with an invalid joint: Plugin option main_group with SIMPLEX_MCP_MACHINE: a valid SimpleX name of at most 50 characters expected, got NAME. Change one of them. The hooks receive the variables from Claude Code. The MCP server gets them from .mcp.json, where ${user_config.KEY} is mapped to the same names.
File Content
.claude-plugin/plugin.json name simplex, version 0.3.0, equal to package.json, description, author, homepage, repository, license, keywords, userConfig
.mcp.json server simplex: node ${CLAUDE_PLUGIN_ROOT}/dist/cli.js session with the three option variables, and timeout 169800000 ms
hooks/hooks.json The SessionStart hook runs node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" hook session-start, with timeout 600 s. The command of PreToolUse, with matcher mcp__plugin_simplex_simplex__.*, is node "${CLAUDE_PLUGIN_ROOT}/plugin/allow.js". UserPromptSubmit, Stop, PostModelSwitch and PostCompact use node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" hook turn, with async: true, and so do a second PreToolUse entry, PostToolUse and PostToolUseFailure, each with matcher *. The second PreToolUse entry also has a hook of type mcp_tool: it calls the tool pre_tool_use of the server plugin:simplex:simplex with the input {"tool": "${tool_name}"}, with timeout 5 s (4.1). MessageDisplay runs node "${CLAUDE_PLUGIN_ROOT}/dist/display.js", with timeout 2 s, without async: Claude Code runs this event's hooks in the foreground
package.json files: the build, README.md and the plugin files, without a lockfile. With bundleDependencies: true, the pack bundles the production packages of node_modules, the dependencies and their dependencies, and no development package. prepack deletes dist and builds it again. Claude Code installs a plugin's dependencies only when bun.lock, npm-shrinkwrap.json, package-lock.json or bun.lockb is in its folder. So it installs nothing here, and the plugin loads its bundled modules
package-lock.json the tree that npm ci installs for development and in build.yml before the publication. Its production packages are marked inBundle. It is not packed
plugin/allow.js prints {"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}
dist/display.js the MessageDisplay hook, built from src/display.ts, see below
dist/status-line.js the status line command, built from src/status-line.ts, see below
/.claude-plugin/marketplace.json marketplace simplex-chat, plugin simplex, source {"source": "npm", "package": "@simplex-chat/mcp"}

Hook input fields used (SessionStartInput, TurnInput, Origin, TranscriptEntry, Usage):

  • SessionStart: session_id, session_title, cwd, model and source. With source compact, the model is not sent.
  • The other hooks: session_id, hook_event_name, transcript_path, prompt_id, prompt, last_assistant_message, to_model and effort.level. Of the turn hooks, only Stop has effort; the tool hooks have it too.
  • The tool hooks also: cwd, agent_id, tool_name, tool_input, tool_use_id, duration_ms and is_interrupt.
  • PostCompact also: agent_id.
  • MessageDisplay: session_id, message_id, index, final and delta.

Claude Code 2.1.322 runs the MessageDisplay hook while Claude's text of the main conversation streams in the terminal: once for each batch of whole lines, at most every 100 ms and up to 3 at once, and once more with final: true and the rest of the text at the end of the model's response. In claude -p and Agent SDK runs it runs once for each response, with the whole text. Claude Code shows each batch in the terminal once the hooks of that batch return. dist/display.js loads only Node modules, paths.ts and service-request.ts, so it returns quickly. It sends {id: session_id, pid, at, text: {message: message_id, index, final, delta}} with POST /turn, waits for the reply at most 1 s, and prints {}. It starts no service, makes no retry and prints nothing about failures; an input without session_id, message_id or a whole index sends nothing. The service answers 409 for a session it does not know, as for a claude -p run (display, postToService, paths.ts).

The Stop hook reads type, isSidechain, message.model and the text parts of message.content from the last entries of the transcript (lastAnswer, transcriptEntry, textOf). It reads the transcript up to 20 times, 100 ms apart, until Claude's last entry is the answer. A missing transcript is read again, as a transcript without that entry is (answerReads, answerRecord, findInTranscript).

The Stop hook then sends usage, the text DURATION · OUTPUT output tokens · CONTEXT tokens in context of its turn (usageTailBytes, tokenCount, turnUsage, usageOf, startsTurn, timeOf, count):

  • The turn's first entry is the first user entry of the main conversation, not a tool result, whose promptId is the hook's prompt_id. The hook looks for it in the tail of the answer's read, and then in the last 4, 16 and 64 MiB of the transcript, until one has it. It parses only the lines that contain that ID or an assistant entry.
  • DURATION is the answer's timestamp minus the first entry's, in the format of the step lines.
  • OUTPUT is the sum of message.usage.output_tokens over the distinct message.id of the assistant entries after the first entry, without subagent entries and <synthetic> entries. Claude Code writes one entry per content block of a response, each with the response's usage.
  • CONTEXT is input_tokens + cache_creation_input_tokens + cache_read_input_tokens of the answer's entry, as Claude Code counts the context in use.
  • Tokens are shown in the compact notation of Intl.NumberFormat, as in the note of a compaction: 861, 1.6K, 16K, 673K, 1.2M.
  • No usage is sent without prompt_id, for an answer that is not found, is <synthetic> or has no message.usage or timestamp, or when the first entry is not in the last 64 MiB.

The PostModelSwitch hook sends to_model as model, with switched: true (turn).

Claude Code runs the person's statusLine command through a shell after each response of the model, at changes of the model, the effort level and other inputs, and at the reset of a usage window. It passes the input on stdin, with CLAUDE_PID in the environment. It refuses ${CLAUDE_PLUGIN_ROOT} in that command, which belongs to no plugin. The service writes ROOT/status-line.js at each start, import(URL).then(module => module.runStatusLine()) with the URL of its own dist/status-line.js, through a temporary file renamed into place, readable only by the user; a failed write is logged (writeStatusLine, Service.start, productionDeps). The setting node "${SIMPLEX_MCP_HOME:-$HOME/.simplex-mcp}/status-line.js" reaches that file in each machine or container. Claude Code runs that file also when no service could start in that folder, so the folder must be writable only by the user. dist/status-line.js loads only Node modules, paths.ts and service-request.ts (statusLine, limitParts, runStatusLine):

  • It prints the parts known of model.display_name, effort LEVEL from effort.level, N% context from context_window.used_percentage, 5 h: N% and week: N% from rate_limits.five_hour and seven_day, joined by ·, with each percentage rounded down.
  • Then it sends {id: session_id, pid, at, effort, limits, statusLine: true} with POST /turn, when it has an effort level or a window. limits holds fiveHour and week, each {percent, resetsAt} from used_percentage and resets_at. It waits for the reply at most 1 s, starts no service and makes no retry.

The UserPromptSubmit hook finds the prompt's record among the last entries of the transcript. A record is a user entry, without subagent entries and tool results, or a queued_command attachment, the record of a prompt that Claude Code added to a running turn. The record is the newest one whose text equals the prompt: the entry whose promptId equals the hook's prompt_id, or a record after the first entry with that ID. Claude Code gives the hook of a prompt added to a running turn that turn's prompt ID, and the turn's tool results carry it too, so the first entry with that ID is found also when the turn's first entry is out of the tail. Until an entry with prompt_id is in the tail, the hook waits for it, and at the last read it takes any record with the prompt's text. While a queue-operation enqueue entry with the prompt's text follows the record, the hook waits too: the prompt is a later one with the same text, still queued. Without prompt_id, as in older Claude Code, it takes any record at once. typed is true when the record's origin.kind is human, and midTurn is true when the record is not the entry with prompt_id. Claude Code writes the entry only after the synchronous UserPromptSubmit hooks end, and it creates the transcript file with the session's first entry. So the hook reads the transcript up to 600 times, 100 ms apart. A missing transcript is read again, as a transcript without the entry is. Claude Code runs the hook of a person's prompt when it is submitted, and of its own prompts only when they are taken. So at the last read, the hook classifies a record still followed by such an enqueue entry by the record, and marks a typed one mid-turn: the queued prompt is the typed prompt itself, or a later prompt with the text of Claude Code's own prompt. When no record is found within these reads, an enqueue entry with the prompt's text after the entry with prompt_id, or anywhere without that entry, makes the prompt typed and mid-turn. Otherwise typed is true when an entry with prompt_id has the origin human (promptReads, transcriptReadMs, promptKind, findInTranscript, promptRecord, isPrompt, recordText, recordKind).

The UserPromptSubmit hook's note is a line of at most 200 characters; a longer one is cut to 199 and ends with …. It is sent in small print, !- NOTE!, with each ! of NOTE replaced with ǃ (small). A typed prompt, a channel prompt, a teammate's prompt of idle notifications only and another record without origin that is not scheduled have no note (recordKind, noteOf, taskNote, teammateNote, idleNotification, peerName, firstLine, decoded, stringOf, shortened):

Kind Record Line
task notification origin task-notification, or a queued_command attachment without origin whose commandMode is task-notification an emoji, the first line of <summary> or Task notification, and : with the first line of <event> when there is one. Entities are decoded. The emoji is ✅ for <status> completed, ❌ for failed, ⏹️ for stopped or killed; without a status, 📡 with an event and 🔔 without. A prompt without a <task-notification> block gets 🔔 and its first line
message of another session origin peer ✉️ Message from NAME: and the first line of body. NAME is name, or from
message of a teammate no origin; the prompt starts with Another Claude session sent a message and a <teammate-message teammate_id="NAME" ...> tag ✉️ Message from NAME: and the tag's summary, or the first line of the message without one, from the first tag whose message is not an idle notification, a JSON type of idle_notification. A prompt with idle notifications only has no note
subagent report origin peer with handback 📋 Report from subagent NAME: and the first line of handbackReportText, or of body
scheduled prompt no origin, turnOrigin scheduled ⏰ Scheduled prompt: and the first line of the prompt
automatic prompt origin auto-continuation 🔄 Automatic prompt: and the first line of the prompt
another kind another origin ⚙️ Claude Code: and the first line of the prompt

A first line is the first line with other than blank characters. In a first line and in NAME, control and format characters become spaces, so a note is one line.

A tool hook sends step with tool_use_id as id (turn, stepOf, stepText, displayPath, duration). Its text, cut as a note, from the first lines of the fields of tool_input:

Tool Text
Bash 💻 and description, or command without a description
Read, Edit, Write 📖 Read PATH, ✏️ Edit PATH, 📝 Write PATH. PATH is file_path, relative to cwd unless the relative path is absolute or starts with ..
Grep, Glob 🔍 Grep PATTERN in PATH, 🔍 Glob PATTERN in PATH. PATTERN is pattern, and PATH is path, shown as for Read; in PATH is left out without a path or for cwd itself
WebFetch 🌐 Fetch and url
WebSearch 🔎 Search and query
Agent 🤖 Agent: and description
another tool 🔧 TOOL, and : with the first of description, query, url, file_path, path, pattern and command that is not blank

At PreToolUse, step is {id, text: "!- TEXT!"}. At PostToolUse and PostToolUseFailure, it is {id, text: "!- TEXT OUTCOME DURATION!", end: true}. Both are in small print; each ! of TEXT is replaced with ǃ (U+01C3), which looks the same, because ! would end the small print. OUTCOME is left out with its space for PostToolUse, ⏹️ for PostToolUseFailure with is_interrupt true, and ❌ for another PostToolUseFailure. DURATION, from duration_ms rounded to whole milliseconds, is N ms below 1 s, and otherwise rounded down: N.N s below 10 s, N s below 1 min, M min S s below 1 h and H h M min from 1 h; without duration_ms it is left out with its space. The PostToolUse of a tool use whose run_in_background is true is !- TEXT (in background)!: Claude Code ends such a tool use when it starts the command or the agent, and the completion is reported by a task notification. A tool hook without tool_use_id or tool_name, with agent_id, of a subagent, or of a tool whose name starts with mcp__plugin_simplex_simplex__ sends nothing. The matcher of the tool hooks is *, and the hook skips the plugin's tools: Claude Code 2.1.322 tests a matcher as a JavaScript regular expression locally, and with another engine in a cloud session, which refuses some patterns with This hook's matcher cannot be tested in a cloud session: it has to be rewritten. (uTr, binary offset 291099155).

The PostCompact hook reads type, subtype, isSidechain, timestamp and compactMetadata of the transcript's entries with "compact_boundary", and decodes a tail only when its bytes contain that text. It takes the last entry of type system and subtype compact_boundary without isSidechain, whose timestamp is no earlier than 60 s before the hook started and no later than 5 s after it. Claude Code writes that entry during a turn with the records of its next request, and after /compact or in an idle session at once, so the hook reads the last 4 MiB of the transcript up to 120 times, 1 s apart. An input with agent_id, the compaction of a subagent since Claude Code 2.1.323, is not read, and nothing is sent for it or without such an entry. The note is ⚙️ Context summarised , then on request for trigger manual and automatically otherwise, then : PRE → POST tokens when preTokens and postTokens are numbers, in the compact notation of Intl.NumberFormat, such as 968K (eventFields, compactionNote, recentBoundary, compactionReads, compactionReadFactor, compactionAge, compactionSkew, compactionTailBytes, boundaryMarker, tokenCount).

SessionStart output (sessionStart, markUnattended):

Case Output
a run that is not interactive (4.1) {}, after /title with unattended when CLAUDE_CODE_SESSION_ATTENDED is 0 and the entrypoint is an interactive one
Node.js below 22 {"systemMessage": "SimpleX MCP needs Node.js 22 or later; found V."}
owners present, or no link {}
no owner, a link systemMessage: SimpleX MCP: scan this QR code with the SimpleX app and tap Join to supervise your agents in "MAIN":, the plain QR code and the link
service not running after the start {"systemMessage": "SimpleX MCP: The SimpleX service stopped; it starts again with the next tool call."}
other errors, invalid options included {"systemMessage": "SimpleX MCP: TEXT"}