* 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%
138 KiB
SimpleX MCP server: API
The six MCP tools, the agent control chat commands, replies and cards, and the CLI of
@simplex-chat/mcp0.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
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 |
targetincognito (default false)message (default null) |
send |
chattext (default null)file (default null)as (default null)reply_to (default null)mention (default null) |
download |
chatitem |
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 knowncontactAddress other than ok, known, contactViaAddress and connectingConfirmReconnectgroupLink 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 |
chattypenamesimplex_name, when verifiedpeer_type, when presentincognitoknown_as, when incognitoconnectedunread: chatStats.unreadCountapproved: true, only under a standing approval of messages in mode requests |
actions |
actiontoolinput: the input of the creating callstateopen: 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_reviewapiDeleteChat(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 namedirectRcv: contact display namechannelRcv: channel display namesent 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 namedirectRcv: contact display namegroupSnd, directSnd: the agent's name in that chat, its incognito name in an incognito chatchannelRcv, 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 filesfailed: 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 filereceived: rcvComplete, a file at the download path, and fileSource at the download path or the forwarded pathoffered: 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 | keywordlabelparams, when present |
| menu | labelcommands: 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 chatsdone: I sent a message to ... |
text, one code span per line with file: attaching TYPE `PATH`, SIZEreplying to NAME: QUOTE with reply_to, the quote cut to 100 charactersmentioning @A, @'B C' with mention |
download |
I want to download a file from SENDER in KIND NAME (CHAT):, without SENDER in outside groupsdone: I downloaded a file from ... |
`NAME`, SIZEan 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 afterAction 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 modehostor under a standing approval is posted after the action, and its prefix isAction N was performed; its card was not posted:orAction N failed; its card was not posted:. When the core refuses an edit this way, the prefix isAction N OUTCOME; its card was not updated:, with OUTCOMEwas performed,failed,was rejected,expiredorended. - 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).
2.3 Other posts
| 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 ENTRIESnone 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: DATAApproval 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 > 0Stopping: sending K cancelled card(s), up to S s. Ctrl-C to stop now. when cards were edited or posted and S > 0Stopped. |
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
statusof Claude Code's record of the session server's parent,CLAUDE_CONFIG_DIRor~/.claude, thensessions/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 thanbusy,waiting,idleandshellis 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 sessionsfor the K left out (1 older sessionfor 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 aslist of sessions: ERRORonce, 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 reactionmeta.from: the sender's display namemeta.item: the item ID in the session group, as a string; for a reaction, the reacted message's IDmeta.file: the path of the prompt's file, when it has onemeta.reply_to: the quoted item's ID, as a string, when the group has it; for a reaction, the reacted message's IDmeta.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_idbehavior: 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
mainGroupdiffers.
/session requests the session's mode (Session.requestMode, askMode, setMode, declineHost, Hub.onEvent, the Session constructor):
requestsapplies at once. The hub ends a pending mode card and clearshostDeclined.- For
host, the hub posts the mode card when the group has an approver andhostDeclinedis 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
hostDeclinedin session.json. - The hub keeps the mode of an approved card, and a later
requests, asmodein 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_IDandCLAUDE_PROJECT_DIR: the session.CLAUDE_PID: the Claude Code process of a hook.CLAUDE_CODE_ENTRYPOINTandCLAUDE_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_APPROVEandCLAUDE_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: ERRORandpermission relay: ERROR. - The SessionStart hook of an unattended run writes
SimpleX MCP session start: ERROR, and the turn hookSimpleX 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., ora valid SimpleX name expectedwhen 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,modelandsource. Withsourcecompact, the model is not sent. - The other hooks:
session_id,hook_event_name,transcript_path,prompt_id,prompt,last_assistant_message,to_modelandeffort.level. Of the turn hooks, only Stop haseffort; the tool hooks have it too. - The tool hooks also:
cwd,agent_id,tool_name,tool_input,tool_use_id,duration_msandis_interrupt. - PostCompact also:
agent_id. - MessageDisplay:
session_id,message_id,index,finalanddelta.
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
promptIdis the hook'sprompt_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
timestampminus the first entry's, in the format of the step lines. - OUTPUT is the sum of
message.usage.output_tokensover the distinctmessage.idof 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_tokensof 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 nomessage.usageortimestamp, 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 LEVELfromeffort.level,N% contextfromcontext_window.used_percentage,5 h: N%andweek: N%fromrate_limits.five_hourandseven_day, joined by·, with each percentage rounded down. - Then it sends
{id: session_id, pid, at, effort, limits, statusLine: true}withPOST /turn, when it has an effort level or a window.limitsholdsfiveHourandweek, each{percent, resetsAt}fromused_percentageandresets_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"} |