From 5f2367fd9d8ab77e3f2a09abb113896ff2fcf392 Mon Sep 17 00:00:00 2001 From: "Evgeny @ SimpleX Chat" <259188159+evgeny-simplex@users.noreply.github.com> Date: Thu, 12 Nov 2026 18:32:13 +0000 Subject: [PATCH] docs: plan the Claude Code plugin and SimpleX channel of the MCP server (#8074) * docs: plan the Claude Code plugin and SimpleX channel of the MCP server * docs: MCP plan, adopting #7810 from its branch * docs: MCP plan, one pull request from the branch of #7810 * docs: MCP plan, a group per session * docs: MCP plan, mirroring the terminal conversation * docs: MCP plan, Claude and User profiles, model and effort * docs: MCP plan, sessions inside one group * docs: MCP plan, sessions as subgroups * docs: MCP plan, one Claude profile, decisions D8-D10 * docs: MCP plan, implementation goal * docs: MCP plan, decisions 27-35 on mirroring and tool use * docs: MCP plan, model and effort change outside the group * plans: plugin launch from its own build, one session per process * plans: hold prompts after a daemon start until the session attaches * plans: publish the plugin with production dependencies only * plan: resumed sessions, turn records, ordered prompts, lock check * plan: quote once, refused quotes, lock wait, cut prompts * plan: hold a new session's title until its server registers * plan: late turn records, tag-only prompts, lock claims, held titles * plan: delete groups of sessions closed 7 days; no group for claude -p * plan: keep the approved mode in the session group, the link off /status * plan: apply leaving, removal and demotion in the Main group to sessions * plan: reply sends a file after an owner's approval when non-owners see it * plan: the line count is an estimate; done is complete and tested * plan: resumes after deletion, User's group, unattended runs, reply cards * plan: trust model of the Main group; review-driven changes removed Adds the Trust model section set by the user, rewrites decision 17, and marks decisions 60, 62, 63 and 64-66 as removed by the user's rule on reviews; the sections on closed sessions, runs without a group, the cascade of Main group changes and User's newest group are removed, and the reply section follows rule 5. * plan: no group for claude -p kept, the unattended mark, the MCP era test Decision 60 keeps the runs without a group, by the user's answer R1 B, with the amendment of the unattended mark; only the deletion of closed groups stays removed, with decisions 64 and 65. Decision 66 is restored, decision 69 records the test of the protocol revision, the section on runs that are not interactive returns with its diagrams, and the channel instructions follow the trust model. * plan: //, /!, guest prompts, parts of a message, approve_guest_files Decisions 70-73 record the user's answers: // and /! with the approved texts, Unknown command. as a placeholder, guests' prompts with approvals kept, the option approve_guest_files; decisions 17, 33, 41 and 53 are rewritten; the trust model, the mechanics, the diagrams and the pending texts follow. * plan: large replies, User's commands, part search, reply size, marks Decision 50 covers a post refused as largeMsg; decisions 74-77 record User's dropped commands, the search of a part within one message size, the reply's message size check and the removal of old unattended marks; the mechanics and diagrams follow. * plan: a reset of the owners leaves the session groups as they are Decision 78 records the user's decision by rule 4 of the trust model; the Groups section and its diagram follow. * plan: the corrected trust model: every session member controls it The trust model is replaced by the user's corrected one; decisions 79-83 record every member's control, the join post with /observer, the /observer command, files approved by owners of the Main group with approve_files, and the start notice pending; decision 71 takes the user's text; the mechanics, diagrams and the pending texts follow. * plan: the role model of session groups Rights in a session group follow the member's role there: admins and owners prompt, approve and send // and /!; moderators, members and authors prompt; /join N invites as admin; Claude posts the member's rights at each join and role change; files of reply are sent at once under the group's preference for files and media; session groups keep no invited records. Decisions 84-89, and proposal 90 for the profile kept from groupUpdated. * plan: / commands from admins and owners, profile updates from the current profile Decision 92 records that every message of a member who sends is a prompt except / commands, // and /!. Proposals 90, profile updates from the group's current profile, and 91, one refusal of the / commands of moderators, members and authors, wait for the user. * plan: diagrams render whole on GitHub Semicolons and # in sequence messages, notes and state transitions are written as #59; and #35;, and the second colon of a state note as #58;. All 26 diagrams of the plan render with GitHub's Mermaid viewer, each text in full. * plan: /observer and profile updates after review round 7 Decisions 93-96: /observer reads the members again after the role change; it answers that a member who has not joined yet is no member; profile updates of a session group run one at a time; the code has no comments. * plan: rights texts of the UX page's recommended branch Decision 97: the rights texts name / commands, and the owner's post has no /observer command. * plan: session group description of the UX page's recommended branch Decision 98: the session group's description, set at its creation. * plan: Main group welcome and join post, approved as B1 and B2 * plan: Main group short description, T3 of the UX page * plan: Main group reply to an unknown command, G6 of the UX page * plan: reply answers the files refusal with its own text * plan: Main group texts set at its creation, UX-F3 a * plan: admins and owners in the texts outside the group, rule 3 * plan: no reply to commands of members past the one refusal, U2 a * plan: expiry timers wait at most 60 s, review round 8 F1 * plan: text cards while media are off, review round 8 question 2 a * plan: /forward while media are off, review round 8 question 3 a * plan: decision 93 names when an observer's approvals count again * plan: serve passes the 0.2 tests unchanged, review round 8 question 1 b * plan: the UX page's new address * plan: premises, and open decisions decided by judgement but UX-I1 * plan: decision 31 reads the effort level from every turn hook, as the code * plan: decisions 107 and 109 state the behaviour exactly, round 9 N2 N3 * plan: one text names a refusing group preference; serve /give as 0.2 * plan: decision 76 without the card reply no longer has * plan: decision 114, a refused outcome card leaves the action done * plan: decision 114, a refused outcome card says the action was performed * plan: decision 114, a refused prompt of User says it is not allowed for User * plan: decision 114, a card refused after the decision names the outcome * plan: decision 114, the one-period log line is the plugin's; serve keeps 0.2's * plan: decision 113 b, the user's answer: reset-owners needs no approval * plan: decision 116, the service, and root files no agent name can take * plan: decision 117, the user's answer: // and /! are removed * plan: decision 118, the user's answer: the plugin's skills are removed * plan: decision 21 names the PreToolUse hook's plugin/allow.js * plan: decision 119, the user's answer: bundled dependencies, no lockfile * plan: decision 120, the user's answer: plugin-only README, shared settings * plan: decision 31, the Stop hook sends the model of its answer * docs: the MCP server's PLAN.md moves to plans/2026-10-19-mcp-server.md * plan: decisions 121 and 122, typed prompts and the newest model --- packages/simplex-chat-mcp/REFERENCE.md | 6 +- packages/simplex-chat-mcp/spec/README.md | 2 +- packages/simplex-chat-mcp/spec/api.md | 2 +- .../simplex-chat-mcp/spec/architecture.md | 4 +- .../PLAN.md => plans/2026-10-19-mcp-server.md | 0 plans/2026-11-07-mcp-claude-code-channel.md | 1130 +++++++++++++++++ 6 files changed, 1137 insertions(+), 7 deletions(-) rename packages/simplex-chat-mcp/PLAN.md => plans/2026-10-19-mcp-server.md (100%) create mode 100644 plans/2026-11-07-mcp-claude-code-channel.md diff --git a/packages/simplex-chat-mcp/REFERENCE.md b/packages/simplex-chat-mcp/REFERENCE.md index ec381602cb..ea886b9ed0 100644 --- a/packages/simplex-chat-mcp/REFERENCE.md +++ b/packages/simplex-chat-mcp/REFERENCE.md @@ -15,7 +15,7 @@ What it isn't: - a Claude Code plugin or channel; - registration in other hosts. -Status: v0.2. [`TESTING.md`](TESTING.md) describes a local build and test. The design, the tools and the scenarios are in [`PLAN.md`](PLAN.md). +Status: v0.2. [`TESTING.md`](TESTING.md) describes a local build and test. The design, the tools and the scenarios are in the [design record](../../plans/2026-10-19-mcp-server.md). - [Requirements](#requirements) - [Quick start](#quick-start) @@ -259,7 +259,7 @@ Commands: After `/leave #9`, or after the agent's `leave` of #9 is performed in either mode, when the chat's folder has files, the agent posts ``Files from business Ridgeline (#9) are kept in `/home/alice/.simplex-mcp/my-agent/files/group-9`: 3 files, 2.1 MB. /delete #9 files``. The files forwarded from #9 are deleted when the agent leaves it. -`/pending`, `/list` and `/leave` are in the chat's command menu, and the cards carry the others. Tapping `/leave` in the menu puts `/leave ` into the entry field: replace `` with the chat's ID from `/list`, such as `#9`, and send it. Each command includes its number, because the app sends a tapped command as a new message, without a quote. Every card form and reply is listed in [`PLAN.md`](PLAN.md), section "What the owner sees: the agent control chat". +`/pending`, `/list` and `/leave` are in the chat's command menu, and the cards carry the others. Tapping `/leave` in the menu puts `/leave ` into the entry field: replace `` with the chat's ID from `/list`, such as `#9`, and send it. Each command includes its number, because the app sends a tapped command as a new message, without a quote. Every card form and reply is listed in the [design record](../../plans/2026-10-19-mcp-server.md), section "What the owner sees: the agent control chat". ### Approval of all messages to a chat @@ -315,7 +315,7 @@ An empty file is refused, and so is `as` without `file`. A message holds at most The server checks the file by its real path, after symbolic links, and refuses files under `~/.ssh` and `~/.gnupg`, files named `id_*`, `*.pem`, `*.key`, `*.p12` and `*.pfx`, and the files under its data folder and under `~/.simplex-mcp`, except those under `files/` of its own data folder; each folder is taken by its real path too. The card shows the real path. A file whose real path, size, inode or change time differs at the send from the request is not sent: the action fails. -Incognito: the core creates a random profile for that one chat, so peers of different chats can't link them. The tools' inputs, results and errors are in [`PLAN.md`](PLAN.md), section "What the agent sees: tools", and the call sequences of the scenarios in section "Sequence diagrams". +Incognito: the core creates a random profile for that one chat, so peers of different chats can't link them. The tools' inputs, results and errors are in the [design record](../../plans/2026-10-19-mcp-server.md), section "What the agent sees: tools", and the call sequences of the scenarios in section "Sequence diagrams". ## Waiting for approval in Claude Code diff --git a/packages/simplex-chat-mcp/spec/README.md b/packages/simplex-chat-mcp/spec/README.md index 745d9497b3..69006ddc00 100644 --- a/packages/simplex-chat-mcp/spec/README.md +++ b/packages/simplex-chat-mcp/spec/README.md @@ -2,7 +2,7 @@ > Technical specification of `@simplex-chat/mcp` 0.2.0 in `packages/simplex-chat-mcp`. Statements are checked against the source at commit `937a975a6`, and each section links to the code. > -> Related: [README](../README.md) (user manual) | [PLAN](../PLAN.md) (design record) | [TESTING](../TESTING.md) (local build and test) +> Related: [README](../README.md) (user manual) | [PLAN](../../../plans/2026-10-19-mcp-server.md) (design record) | [TESTING](../TESTING.md) (local build and test) ## Table of contents diff --git a/packages/simplex-chat-mcp/spec/api.md b/packages/simplex-chat-mcp/spec/api.md index e411fb3b56..bbad2bd3bc 100644 --- a/packages/simplex-chat-mcp/spec/api.md +++ b/packages/simplex-chat-mcp/spec/api.md @@ -478,7 +478,7 @@ Command lines ([`commandsLine`](../src/control.ts#L603-L616)): | `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](../PLAN.md#what-the-owner-sees-the-agent-control-chat)). +The app shows `/'approve N'` as the tappable command `/approve N` ([PLAN, What the owner sees](../../../plans/2026-10-19-mcp-server.md#what-the-owner-sees-the-agent-control-chat)). 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.ts:145-152](../src/control.ts#L145-L152), [:495-497](../src/control.ts#L495-L497)). diff --git a/packages/simplex-chat-mcp/spec/architecture.md b/packages/simplex-chat-mcp/spec/architecture.md index 4f35bd70ff..aeee1fe94d 100644 --- a/packages/simplex-chat-mcp/spec/architecture.md +++ b/packages/simplex-chat-mcp/spec/architecture.md @@ -3,7 +3,7 @@ > System structure, modules, state, process lifecycle, approval model and security boundaries of `@simplex-chat/mcp` 0.2.0. > > Related specs: [README](README.md) | [Flows](flows.md) | [API](api.md) -> Related docs: [README](../README.md) | [Reference](../REFERENCE.md) | [PLAN](../PLAN.md) +> Related docs: [README](../README.md) | [Reference](../REFERENCE.md) | [PLAN](../../../plans/2026-10-19-mcp-server.md) **Source:** [`cli.ts`](../src/cli.ts) | [`serve.ts`](../src/serve.ts) | [`http.ts`](../src/http.ts) | [`tools.ts`](../src/tools.ts) | [`actions.ts`](../src/actions.ts) | [`control.ts`](../src/control.ts) | [`messages.ts`](../src/messages.ts) | [`files.ts`](../src/files.ts) | [`register.ts`](../src/register.ts) | [`log.ts`](../src/log.ts) @@ -622,7 +622,7 @@ The server writes the tappable form `/'...'` only in the card's command line ([c - The join link is a group link of the control chat with role `member`, or `observer` with `--owners`; it is printed with a QR code on stdout and deleted at the first join event ([control.ts:406-416](../src/control.ts#L406-L416), [:372](../src/control.ts#L372), [:381](../src/control.ts#L381)). - At every start the server sets private message routing: `smpProxyMode` `always`, `smpProxyFallback` `allowProtected` ([serve.ts:91-92](../src/serve.ts#L91-L92)). -- With `incognito: true` the join methods connect incognito ([tools.ts:721](../src/tools.ts#L721)); the core then uses a random profile for that chat ([PLAN, Participants](../PLAN.md#participants)). +- With `incognito: true` the join methods connect incognito ([tools.ts:721](../src/tools.ts#L721)); the core then uses a random profile for that chat ([PLAN, Participants](../../../plans/2026-10-19-mcp-server.md#participants)). --- diff --git a/packages/simplex-chat-mcp/PLAN.md b/plans/2026-10-19-mcp-server.md similarity index 100% rename from packages/simplex-chat-mcp/PLAN.md rename to plans/2026-10-19-mcp-server.md diff --git a/plans/2026-11-07-mcp-claude-code-channel.md b/plans/2026-11-07-mcp-claude-code-channel.md new file mode 100644 index 0000000000..6d361b9f6c --- /dev/null +++ b/plans/2026-11-07-mcp-claude-code-channel.md @@ -0,0 +1,1130 @@ +# SimpleX MCP 0.3.0: Claude Code plugin and SimpleX channel + +Status: draft for review. Code references: master `2abd48450` (MCP 0.2.0); #7810 at `a7953a767`. Claude Code references: https://code.claude.com/docs/en/channels, https://code.claude.com/docs/en/channels-reference. + +Outcome: +- Claude Code users install SimpleX with `/plugin install`, scan one QR code and join the Main group. +- Each Claude Code session has its own group with its owners; one `Claude` profile holds the chats of all sessions. +- Owners prompt a running session in its group; the session receives the prompt without polling. +- Owners approve the session's tool use (`Bash`, `Write`, `Edit`) in its group. +- `simplex-mcp serve` keeps serving other MCP hosts over HTTP. + +## Implementation goal + +One PR that publishes `@simplex-chat/mcp` 0.3.0: Claude Code users install the plugin, join one Main group, and run each Claude Code session from its own SimpleX group, with prompts from the phone, the session mirrored, and tool use approved there; `serve` is unchanged for other hosts. + +Done when: +``` +# criterion checked by +1 /plugin install; first session shows the QR code in the terminal, never in Claude's context unit test of the hook output; real session +2 an owner joins the Main group and gets a "Tap to join" card for each session's group end-to-end test +3 an owner's message in a session group reaches the running session as a channel event real session with the development flag +4 Claude's answer is posted by Claude; a prompt typed in the terminal is posted by User end-to-end test of the hooks; real session +5 a Bash prompt becomes a card; /approve runs the tool, /reject refuses it real session +6 connect, send, download and leave cards in the session group; chats owned by sessions; /give end-to-end tests +7 the group description shows the model and effort and follows a change unit test; real session +8 decisions 17-23 hold unit tests +9 serve: all 0.2 unit and end-to-end tests pass unchanged the run "The tests of 0.2" of TESTING.md +10 feature complete and tested; the source lines are an estimate, not a limit review report +11 one page presents the PR; an independent reviewer confirms it matches the diff review report +``` + +Real-session checks run in an interactive Claude Code session started with `--dangerously-load-development-channels plugin:simplex@simplex-chat`; the user runs them or allows them. + +## Decisions + +Premises, from which the decisions follow: +1. Rights follow the visible role. +2. Everything in a session group is addressed to Claude; commands steer it and are for admins and owners. +3. Owners own the group's settings; Claude changes only what it wrote. +4. `serve` stays as published in 0.2. +5. #7810's features stay unless they conflict. + +On 2026-11-09 every decision below that was proposed, recommended or open is decided by our judgement, as implemented; the user gives feedback once using the plugin. The one question left open, UX-I1 (decision 113), was decided by the user on 2026-11-10. + +Agreed on 2026-11-06: +1. `serve`, `register` and HTTP stay. +2. #7810's code is adopted with `serve` kept; shum reviews the result. +3. The plugin is released as 0.3.0. + +Decided on 2026-11-07: +4. One PR: branch `ep/mcp-plugin` from `sh/mcp-known` in the agents' fork, against master; it replaces #7810. +5. The PR reaches the user as one page that presents it; an independent reviewer checks the page against the diff before the user sees it. +6. D1 (b): one group per session. The hub invites the Main group's owners to it through the Main group; other members of the Main group join it by `/join N`. +7. D2 (a): every tool prompt of a session is relayed to its group. +8. D3 (a), replaced by D8 (a): peers see `Claude`, or an incognito name in a chat connected incognito. +9. D4 (a): files in prompts and in replies are in this PR. +10. D5 (a): the user asks Anthropic to list the channel after 0.3.0 is published. +11. D6 (a): the hub, the plugin's main profile, speaks for Claude: it posts the session's answers and cards in the session's group. Its profile name is `Claude`. +12. D7 (a): prompts typed in the terminal are posted in the session's group by a local profile named `User`, one per data root, a member of every session group. +13. D8 (a): one `Claude` profile, in the service's one process, serves all sessions of a data root: it hosts the Main group and the session groups and holds the chats with peers. A chat belongs to the session that connected it; tools of other sessions do not show it; owners hand it to another session with `/give CHAT N` in the session's group. +14. D9 (a): the session group's description shows the model and the effort level and is updated when they change; they are changed in the terminal or from the Claude app by Remote Control. +15. D10 (b): 0.3.0 ships with a group per session; the plugin moves each session group into a session of the Main group when the apps support group sessions. A UX proposal for group sessions is prepared separately, now. + +Design: +16. One code base: `serve` and the plugin share `Control`, `Actions` and `AgentTools`. +17. Prompts count from every member of the session group but `User`; approvals, tool-use verdicts and the group's commands count from its admins and owners, whatever way they joined (rewritten on 2026-11-08 by the [trust model](#trust-model) and decision 84; amended on 2026-11-10 by decision 117). +18. The owner link reaches the person only: the `systemMessage` of the SessionStart hook and `simplex-mcp link` in a terminal; hook context and tool results never contain it. +19. A session's approval mode changes to `host` only after an owner approves a card in the session's group. +20. Replaced on 2026-11-10 by decision 113. It was: while owners exist, an owner reset runs only after an owner approves a card in the Main group; without owners it runs from a terminal. +21. The package bundles its production dependencies (decision 119); the plugin's server and hooks run `node ${CLAUDE_PLUGIN_ROOT}/dist/cli.js`, except the PreToolUse hook, which runs `node ${CLAUDE_PLUGIN_ROOT}/plugin/allow.js`, and Node resolves its modules from the plugin's folder (replaces npx in the plugin folder, 2026-11-08; amended on 2026-11-10 by decision 118 and on 2026-11-11 by decision 119). +22. Refused paths cover the whole data root. +23. Standing approvals of closed sessions are listed by `/list` and removed by `/revoke` in the session's group. +24. The channel is part of the plugin's session server; the service pushes events on the session's `/attach` stream. +25. The session and its group exist from the session's start. +26. Claude's final answer of every turn is posted by `Claude` from the Stop hook's `last_assistant_message`; the `reply` tool sends files only. + +Decided on 2026-11-08: +27. UserPromptSubmit, Stop and PostModelSwitch post to one service route, `POST /turn`. +28. A tool-use card is an action of tool `permission`; allowed is `performing` then `done`, denied is `rejected`, ended is `expired` with the last line `Ended.`. +29. Open tool-use cards of a session end at each prompt and each answer whose hook started after their creation, and when the session detaches. +30. A decided tool-use action leaves the session's actions at once. +31. The effort level is read from every turn hook whose input has `effort.level`: UserPromptSubmit, Stop and PostModelSwitch each run `hook turn`, which sends it with `POST /turn`, and a changed value updates the group's short description (ep/mcp-plugin at ed2f7a716: hooks/hooks.json:5-7, src/hook.ts:29, :78, src/hub.ts:187-191, :196-197). Corrected on 2026-11-09 to the code; it read: from the Stop hook only. Amended on 2026-11-11: the Stop hook also sends the model of its answer, the `message.model` of Claude's last entry in `transcript_path`, of type `assistant` without `isSidechain`, once that entry's text is the answer, read from the last 1 MiB and twice the answer's bytes up to 20 times 100 ms apart; `` sends none. The model is shown in the short description from the first answer, also when SessionStart has no `model`, as after `claude --resume`; SessionStart's `model` and PostModelSwitch's `to_model` stay. +32. The three mirroring hooks run with `"async": true`. +33. Answers and terminal prompts are posted in parts that each fit one message, measured as the core measures it: `fitsMessage` on the encoded message, with the quote. An answer quotes the prompt only when the quote fits with the answer's first character (rewritten on 2026-11-08). +34. A prompt in the group of a session without an attached Claude Code gets the reply `Session N is not running.` +35. A UserPromptSubmit prompt is not posted by `User` when a channel tag of this server in it holds a pushed prompt with its item ID, when it equals a prompt pushed in the last 60 s, when it is made only of this server's channel tags, or when it is a one-line `/` command. + +Decided on 2026-11-08, review round 1: +36. The hooks and the session server of one Claude Code process share one session: the hooks send `CLAUDE_PID`, the session server its parent PID. The service maps a session ID without `session.json` to the session of that process and records the alias in `session.json`. A hook of an ID with `session.json` goes to the session attached from its process, without an alias. A title of a new ID from a process without a known session, or with a held title, waits for the session server of that process to register, up to 10 s; the turn hooks repeat a refused turn up to 15 times, 1 s apart. A service stop keeps the held titles for the next start. +37. When `/attach` ends or a start fails, the session server starts the service if needed and attaches again: after 1 s, twice as late after each failure, at most 30 s apart, until its stdin closes or the service speaks another protocol. +38. A pending connection of `connect` is recorded in the session group's data for one day; its chat becomes the session's when it connects within that day. A `connect` to a known chat without an owner gives it to the session. +39. Owners' prompts are kept until a turn's prompt matches them, at most 20. Each prompt hook records its start time with the oldest prompt it matched, or none, unless it started before an answer already handled. An answer, also an empty one, quotes the newest record whose hook started before its own; without one, it quotes the oldest kept prompt not quoted yet, and that prompt stays kept for its prompt hook. +40. A session in mode `host` posts its mode card when its group has an approver: at the session start or after a membership event. A rejected card is recorded in `session.json`; the card is posted again only after a session start with `requests`. A change to `requests` ends a pending mode card. +41. Replaced on 2026-11-08 by decision 70. It was: an owner's one-line `/` message is a prompt when its keyword is not a command of the session group. +42. The service is spawned with an allowlist of environment variables, `NODE_OPTIONS` among them. +43. For 30 s after a service start, an owner's prompt to a session without an attachment waits for the session to attach; the reply `Session N is not running.` follows only when it does not. +44. Replaced on 2026-11-11 by decision 119. It was: the published `package.json` and `npm-shrinkwrap.json` hold the production dependencies only: 41 packages and 9 MB to download in place of 317 and 25 MB. The repository keeps the development dependencies; the pack strips them, restores the files after it, and heals a failed pack first; the launch test checks the packed files. + +Decided on 2026-11-08, review round 2: +45. An owner's prompts reach the session in arrival order. A prompt waits for the file of an earlier one, and gets `Session N is not running.` when the session detached meanwhile. +46. Texts that name an npx command name the plugin's version: `npx -y @simplex-chat/mcp@VERSION link`. +47. A spawned service with a held lock checks it for up to 15 s: a released lock starts it; an answering socket reports `running`; otherwise it reports the lock's error and exits with 1. +48. A group profile update keeps the custom data of the group in memory. +49. Replaced on 2026-11-11 by decision 119. It was: the launch test installs the packed plugin with the command of Claude Code 2.1.319, `npm ci --ignore-scripts --workspaces=false --no-audit --no-fund`, within 60 s. + +Decided on 2026-11-08, review round 3: +50. Claude posts an answer or a reply without its quote when the core refuses the quote, as for a deleted prompt, or refuses the post with the quote as too large, `largeMsg` (amended on 2026-11-08, review round 6). +51. The turn hook cuts a prompt or an answer over 250,000 characters there, ending with `…`. +52. `User` posts no empty terminal prompt. +53. Replaced on 2026-11-08 by decision 71. It was: the commands reply of a session group lists `/give`. +54. A Stop request posts the answer before it updates the group's short description. +55. An existing token file is made private only when the user owns it. + +Decided on 2026-11-08, review round 4: +56. The lock and the token are created by linking a complete private temporary file into place; where links fail, by an exclusive write. +57. The lock of a stopped process is taken over through a claim, `lock.PID.claim`, which only one starter creates: a link of the lock, or where links fail an exclusive write; the claimer replaces the lock when the lock still holds that PID. +58. A Stop request updates the short description also when its posts fail. +59. A title's rename writes `session.json` as read after the group's rename. + +Proposed on 2026-11-08, each in its own commit; decided by judgement on 2026-11-09: +60. A run whose `CLAUDE_CODE_ENTRYPOINT` is `sdk-cli` (`claude -p`), `sdk-ts` or `sdk-py` (the Agent SDK), or whose `CLAUDE_CODE_SESSION_ATTENDED` is `0`, gets no session and no group; kept by the user's answer R1 B. Amended on 2026-11-08: the SessionStart hook of a run with `CLAUDE_CODE_SESSION_ATTENDED` `0` and another entrypoint marks its Claude Code process with `/title` `unattended`; the service refuses `/session` from that process with 403 within 10 s of the mark; the refused session server answers every call with the text of a run that is not interactive. Removed by the user's rule on reviews: the deletion of the group of a session closed for 7 days. +61. The approved mode is kept in the session group's custom data, not in `session.json`. `GET /status` returns the owners without the Main group link; `GET /link` returns the link. These protections hold against Claude's tools, not against a shell running as the same user. +62. Removed by the user's rule on reviews; rule 4 of the [trust model](#trust-model) holds. It was: leaving, removal or demotion in the Main group is applied to every session group. +63. Removed by the user's rule on reviews; rule 5 of the [trust model](#trust-model) holds. It was: `reply` posts a file without a card only while every member is Claude, `User`, gone or an owner; the card shows the file's name and size only. + +Decided on 2026-11-08, review round 5: +64. Removed with the deletion of decision 60. It was: a resume during the deletion of its group waits for it; a failed deletion is logged. +65. Removed with the deletion of decision 60. It was: `User` posts in the newest group of the session where its membership is current. +66. Claude Code sets `CLAUDE_CODE_SESSION_ATTENDED` for the hooks of a run; its MCP servers get only the value of the session whose command started the run. `0` makes a run non-interactive; otherwise the entrypoint decides. A real-session check in TESTING records the values. +67. `serve` lists its tools with the metadata of 0.2. + +Proposed on 2026-11-08 with the round 5 fixes; decided by judgement on 2026-11-09, kept: +68. `list` returns the session's actions without its tool-use and mode cards. + +Decided on 2026-11-08, after round 5: +69. A unit test holds the session server's answers to Claude Code 2.1.319: `server/discover` gets `Method not found`, and `initialize` negotiates the revision 2025-11-25. That Claude Code registers no channel for a server in the modern MCP era, 2026-07-28; `McpServer` of the SDK 2.3.1 stays out of it by default. + +Decided by the user on 2026-11-08: +70. Replaced on 2026-11-08 by decision 84. It was: `//` reaches Claude from every member; `/!` only from a member whose member in the Main group is an owner. +71. A one-line `/` text that is not a command of the session group gets `Unknown command.` in place of the list of commands (amended on 2026-11-10 by decision 117; the text set by the user's answer G1 was `Unknown command. To send a command to Claude, start it with //.`). +72. Replaced by decision 79. +73. Replaced by decision 82. + +Decided on 2026-11-08, review round 6: +74. The control of a session group drops the commands of `User`, in the order of the other commands. +75. Each part of a post is searched among the next 15602 characters, the most one message holds. +76. `reply` refuses a caption too long for a message with the file's preview, as `send` does, before its post: `text: too long for a message with this TYPE; shorten it.` (Amended on 2026-11-09: `reply` has no card since decision 87.) +77. Each new unattended mark removes the marks of 10 s ago and older. + +Decided by the user on 2026-11-08, by rule 4 of the [trust model](#trust-model): +78. A reset of the owners leaves every session group as it is: the members invited through the old Main group stay with their roles. + +Decided by the user on 2026-11-08, the corrected [trust model](#trust-model): +79. Replaced on 2026-11-08 by decision 84. It was: every member of a session group but `User` prompts and approves. Kept: the hub reads its contact of `User` at its start. +80. Replaced on 2026-11-08 by decision 86. It was: the join post `NAME can send prompts to Claude and approve tool use. ...` for every role. +81. `/observer #G ID` sets that member's role to observer; Claude accepts it from a member whose role lets them change that member's role in SimpleX: admin or owner, and not below the member's role. Its replies, proposed, are decided by judgement on 2026-11-09; the reply of an accepted one is the observer's rights post of decision 86. +82. Replaced on 2026-11-08 by decision 87. It was: files of `reply` wait for an owner of the Main group to approve their card while the option `approve_files` is on. +83. A session group has no start notice; its description is that of decision 98 (decided by judgement on 2026-11-09; it was: the start notice and the description wait for the user's decision on their place and text). + +Decided by the user on 2026-11-08, the role model of the [trust model](#trust-model): +84. Rights in a session group follow the member's role there, whatever way they joined. Admins and owners send prompts and the group's commands, and approve actions and tool calls. Moderators, members and authors send prompts; their approvals get `Only admins and owners of this group approve actions here.` Observers cannot send (amended on 2026-11-10 by decision 117, which removes `//`, `/!` and the reply to `!`). +85. `/join N` invites a member of the Main group as admin. Owners of the Main group stay invited as owners: at the session start, at their join, and by `/join N` (U1 a, decision 110). Members invited inside the group get the role the inviter sets. +86. Claude posts the member's rights at each join and at each role change in the session group, `User` excepted: `NAME is a ROLE and RIGHTS.`, and for a role that sends ` You can change role to observer to stop it: /'observer #G ID'`. A role change by Claude raises no `memberRole` event; the reply to `/observer` is the observer's post. +87. Claude's files of `reply` reach the session group at once, without a card, in both modes. The group's preference "Files and media", which owners change, is the control; the core enforces it, and the call returns the core's refusal. The option `approve_files`, the cards of `reply`, `/approve N all` and the bare `/revoke` are removed. +88. Session groups keep no record of their invited members. +89. The texts of decisions 84, 86 and 91, as decisions 97 and 105 changed them, are decided by judgement on 2026-11-09; they were placeholders for the UX page. +92. Everything sent in a session group is a prompt to the agent: every message of a member whose role sends is a prompt, except the one-line `/` commands of the group (amended on 2026-11-10 by decision 117). + +Proposed on 2026-11-08 with the role model; decided by judgement on 2026-11-09, 90 as C1 a and 91 as U2 a: +90. Claude's profile updates of the Main group and of session groups read the group's current profile from the chat database and change only Claude's own fields: the name, the short description, the Main group's description and the commands. The preferences owners set, "Files and media" included, stay (C1 on the UX page). +91. The group's `/` commands come from admins and owners only, like approvals. A one-line `/` text from a moderator, member or author gets one reply, `Only admins and owners of this group can send / commands.`, and reaches neither the commands nor Claude. One check, `Session.refusesCommand`, holds it; without it, the reply of decision 71 applies (amended on 2026-11-10 by decision 117). + +Decided on 2026-11-08, review round 7: +93. `/observer` reads the group's members again after the role change, so the standing approvals the new observer gave count no more while that member is not an admin or owner, as after a role change in the app; they stay in the chat's custom data and count again when the member becomes one again (question 4 (a) of review round 8). +94. `/observer` of a member invited who has not joined yet answers `No member ID in this group.` and changes nothing; the member joins with the role of the invitation (the user: "you can't /observer member who is not in the group yet"). +95. Claude's profile updates of a session group run one at a time, so a rename and a change of the model or effort that overlap both stay. +96. The code has no comments. + +Recommended on the UX page (https://claude.ai/artifact/UDxBJx55Y9ti1U3TjUaxpC), one commit each; decided by judgement on 2026-11-09, as implemented: +97. K10, K11: the rights texts name the group's commands (amended on 2026-11-10 by decision 117); the post for an owner has no `/observer` command. +98. A session group's description, set at its creation: `The Claude Code session N. Members send it prompts; admins and owners also send the group's commands and approve tool use.` (amended on 2026-11-10 by decision 117) +100. T3: the Main group's short description is `Everyone in this group can join the groups of your Claude Code sessions, prompt Claude and approve what it does.` +101. G6: the Main group replies `Unknown command.` to a one-line `/` text other than `/sessions` and `/join N`; `/approve reset` and `/reject reset` were removed by decision 113. +102. `reply` answers the core's refusal `feature not allowed Files and media` of decision 87 with FILES OFF: `Files and media are off in the group of this session; its owners can turn them on in the group's preferences.` Other refusals of the core are returned as the core's text. +103. UX-F3 a: the Main group's short description and welcome message are set when the group is created, a reset of the owners included; Claude's later profile updates of the Main group change only its name and commands, so an owner's edits of both stay. Of decision 90, the Main group's short description and description leave Claude's fields. +104. Rule 3 in texts outside the group. The option `approve` reads `requests: you approve connections and messages in the SimpleX app. host: Claude Code asks you instead, after an admin or owner approves this in the session's group.` `connect` to a chat of another session returns `The chat of LINK belongs to another session; an admin or owner of that session's group can give it to this session with /give.` The plugin's limit of pending actions returns `20 actions are pending; wait for the approvers' decisions.`, a text of the hub; `serve` keeps `20 actions are pending; wait for the owner's decisions.` +105. U2 a: the replies of decision 84 to the approvals of moderators, members and authors are removed. The role check stays: in a session group, a request of another role that reaches `Control` gets no reply, and nothing is performed. Decision 91's reply answers these texts first (amended on 2026-11-10 by decision 117, which removes the check of `//` and `/!` in the prompt). + +Decided on 2026-11-09, review round 8: +106. The expiry timer of an action waits at most 60 s and is set again until the expiry time, so an action whose expiry time passes while the computer sleeps expires within 60 s after it wakes, in `serve` as in 0.2. +107. F2-card a, question 2 (a) of review round 8, decided by judgement: in a session group, a card the core refuses with `feature not allowed Files and media` is posted again as text, without the preview, and its later edits are text; sends and downloads of images and videos themselves work as before. `serve` keeps 0.2's behaviour: the action fails with the core's error. +108. Question 3 (a) of review round 8: in a session group, `/forward` whose post the core refuses with `feature not allowed Files and media` gets `Action N: ` + FILES OFF; `serve` keeps ``Action N: the file was not received: `ERROR`.`` +109. S1 b, question 1 (b) of review round 8, decided by judgement: the unit and end-to-end tests of 0.2 (be668564d) pass unchanged on this source. `qrCodeText` is exported from `control.ts` again; `serve` updates its control chat from the profile read at the start, the plugin's groups from the current profile in the chat database (decision 90); a pending action of `serve` that expires is kept until the next owner command or its check 60 s later, as in 0.2, while the plugin's is removed at once when no call is open. An action without a session is an action of `serve`. + +Decided by judgement on 2026-11-09, as implemented: +110. U1 a: owners of the Main group are owners in the session groups (decision 85). +111. Replaced on 2026-11-10 by decision 117. It was: K1 a: a message starting with `!` from any role is refused with `Messages starting with ! reach Claude only from admins and owners, as /!command.` and does not reach Claude; admins and owners send it as `/!` (decisions 84, 92). +112. The notes of the UX page stay as they are: UX-I2, the command `link` (its skill `/simplex:link` removed on 2026-11-10 by decision 118); UX-I3, the plugin's tools without Claude Code's permission prompt; UX-I4, the options Approval and Expiry in hours; UX-I5, the idle close of a session and the idle stop of the service; UX-I6, a newer plugin stops an older service; UX-I8, session numbers. + +Decided by judgement on 2026-11-09, review round 9: +114. Under premise 3, a post of Claude or `User` in a session group that the core refuses with `feature not allowed NAME` is never dropped without a word: Claude posts in its place PREF OFF, `NAME are off in the group of this session; its owners can turn them on in the group's preferences.`, with a subject: `Claude's answer was not posted: `, quoting the turn's prompt; `Action N: ` for a card before the decision, whose action then fails with PREF OFF, for a card posted or edited at a stop, and for `/forward`. After the decision the subject names the outcome and the card, and the action stays as it was: `Action N OUTCOME; its card was not posted: ` for the outcome card of an action performed in mode `host` or under a standing approval, and `Action N OUTCOME; its card was not updated: ` for the edit of a card, OUTCOME being `was performed`, `failed`, `was rejected`, `expired` or `ended`. Claude is an owner of the group, so the core refuses its posts only while a preference is off. `User` joins as a member, and its posts are refused also while NAME is on only for roles above its own: its prompt gets `User's prompt was not posted: ` with USER NOT ALLOWED, `NAME are not allowed for User in the group of this session; its owners can allow them in the group's preferences.` `reply` returns PREF OFF. A media card refused by `Files and media` is first posted again as text (decision 107). One path replaces the code of decisions 102 and 108; their texts are PREF OFF for `Files and media`. The plugin's log line of a failed action ends with one period, also after an error that ends with one. `serve` keeps 0.2's errors and log lines, a period after every error included (premise 4). +115. `serve` answers `/give CHAT N` from any member with the list of commands, as 0.2: `/give` is a request of session groups only. + +Decided by the user on 2026-11-10: +113. UX-I1 b, the replacement of the Main group and its owners. Asked whether anything on the computer that runs Claude Code can replace the Main group without an owner's approval, the user answered: "then obviously this should be possible to reset main group". The person at that computer is trusted with the trust root. `reset-owners` and `POST /reset-owners` replace the Main group at once, also while owners exist; the reset card, `/approve reset` and `/reject reset` are removed. The new link is shown only on a terminal; elsewhere the command names `link`, which shows it on a terminal. The session groups stay as they are (decision 78). `serve` keeps its `--reset-owners` of 0.2. (Amended on 2026-11-10 by decision 118, which removes `/simplex:reset-owners`.) +116. The plugin's process that runs all sessions of a data root is the service; the user: "we should rename them to service. I don't like the word at all and never use it." The command is `simplex-mcp service`, and its files in ROOT are `service.sock`, `service.log`, `service.lock` and `service.token`. Every file of ROOT has a dot in its name, and every folder starts with `_`, which agent names of `serve` can't: `serve NAME` keeps its agent in `~/.simplex-mcp/NAME`, where `token` and `lock` are valid agent names. `serve` keeps its own `lock` and `token` in the agent's folder, as 0.2. +117. `//`, `/!` and the refusal of `!` are removed. Claude Code passes a channel message to Claude as the text of a prompt and runs no command from it (TESTING.md, check 6), so `//` and `/!` ran nothing. The user: "I think both should be removed then, yes, as they make no sense if they are not supported and only add complexity." Under premise 2, every message of a member whose role sends is a prompt, also one that starts with `!`, except a one-line `/` text, which is a command of the group: from an admin or owner, one outside the group's requests gets `Unknown command.`; from a moderator, member or author, every one gets the reply of decision 91. A shell command is asked for in words and runs as Claude's tool use, under Claude Code's permissions. The rights posts and the group's description name the group's commands. It replaces decision 111 and the texts of decisions 71 and 97, and amends decisions 17, 84, 91, 92, 98 and 105. +118. The plugin's skills `/simplex:link` and `/simplex:reset-owners` are removed. Asked whether they are worth keeping, the user: "what's the value having them as commands and not only as CLI options? isn't it just extra moving part that nobody really neads?" `npx -y @simplex-chat/mcp@VERSION link` and `reset-owners` in a terminal stay, with their outputs; the texts that named the skills name `npx -y @simplex-chat/mcp@VERSION reset-owners` in a terminal. The package has no `skills` folder. It amends decisions 21, 112 and 113. + +Decided by the user on 2026-11-11: +119. The package bundles its production dependencies (`bundleDependencies: true`) and is published without a lockfile; the user: "yes, and test it. From what you are saying bundleDependencies is better as it loads one tarball instead of many". Claude Code 2.1.322 installs a plugin's dependencies only when its folder has `bun.lock`, `npm-shrinkwrap.json`, `package-lock.json` or `bun.lockb`, so it installs nothing, and the plugin loads its bundled modules. The tarball holds the production packages of `package-lock.json` and no development package. `npm-shrinkwrap.json` is `package-lock.json` again, for development and for `npm ci` in `build.yml`; `scripts/strip-dev.js` and `postpack` are removed, and `prepack` builds only. The launch test packs a copy installed by `npm ci`, as `build.yml` publishes it, and runs the unpacked plugin without an install. It replaces decisions 44 and 49 and amends decision 21. +120. `README.md` has the plugin's installation and use, and one line that names `REFERENCE.md` for `serve` and `register` and for settings shared by several machines or containers; the user: "README should cover simple plugin installations, running as MCP without channel and running with shared settings can be moved to reference indeed, with a single line in readme." "Try it" merges into the quick start of `REFERENCE.md`, "Prompt your agent from the app" becomes its section "Prompt the agent from the app", and the safety lines of `serve` join its Security. Its section "Shared settings" loads the plugin as in [Launch](#launch), checked with `claude -p --settings` and Claude Code 2.1.322 (TESTING.md, check 17). +121. `User` posts a UserPromptSubmit prompt only when a person typed it. The hook finds the prompt's transcript entry by `promptId`, equal to the input's `prompt_id`, or by its text without one, and skips tool results and sidechain entries. Claude Code writes that entry after the synchronous prompt hooks, in a file created with the session's first entry, so the hook reads up to 600 times, 100 ms apart, and reads a missing transcript again. It sends `typed`, true only for `origin.kind` `human`. The hub posts nothing for `typed: false` and keeps the turn record; a request without `typed` is posted as before. The user reported `User` posting `` blocks; Claude Code's own prompts get one-line posts from Claude in the next pull request (217dcf845, a995eed81). +122. The model and the effort level of the description are taken only from a request whose `at` is not older than the one last taken for each. The SessionStart hook sends its `at` in `/title`, and a held title keeps it in `titles.json` (ae2ed473e, 66646d21c). + +Approved by the user on the PR page on 2026-11-08 (B1, B2): +99. The Main group's welcome message is `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.`, and its post at each join `NAME joined. They can join the group of any Claude Code session here, prompt Claude and approve its actions.` + +The user's rule on reviews, 2026-11-08: "reviewers should have no discretion to drive product changes - the UX was approved, and it must not be changing simply because security reviewers said so." + +Pack of the package (decision 119): +``` +install: npm ci, from package-lock.json: the production and the development packages +prepack: dist deleted; tsc +pack: the tarball: dist, README.md, the plugin files, and node_modules with the production packages + (bundleDependencies); no lockfile +Claude Code: npm pack of the registry tarball, unpacked into the plugin's folder; no lockfile there, so no install +check: launch test: a copy installed by npm ci and packed; no lockfile; exactly the production packages of + package-lock.json; unpacked, a hook and the session server run without an install; an offline install + of the tarball keeps the modules in the package's folder and runs simplex-mcp +``` + +```mermaid +flowchart LR + L[package-lock.json] --> I[npm ci: production and development packages] + I --> P[prepack: dist rebuilt] + P --> T[tarball: production packages in node_modules, no lockfile] + T --> C[Claude Code: unpacks it, installs nothing] + T --> N[npx: installs the one tarball] +``` + +Service start with a held lock (decision 47): +``` +lock of ROOT held by another live process: up to 150 checks, 100 ms apart + ROOT/service.lock gone: start again + GET / on the socket, any reply but ENOENT or ECONNREFUSED: ready line "running" +after the checks: ready line "error: Another service uses ROOT (PID N). If no service runs, remove ROOT/service.lock."; exit 1 +``` + +```mermaid +flowchart LR + L[lock held by a live PID] --> G{lock gone} + G -- yes --> S[start again] + G -- no --> A{socket answers} + A -- yes --> R[running] + A -- no, 150 checks done --> E[error with the lock path, exit 1] + A -- no --> G +``` + +Lock creation and takeover (decisions 56, 57): +``` +create(lock, text): write text to lock.PID.HEX.tmp, 0600; link it to lock; remove the temporary file + link refused other than EEXIST: exclusive write of lock +acquire: create; else read the PID P of lock + P alive and not this process: locked + claim: link lock to lock.P.claim; EEXIST or ENOENT: locked + link refused otherwise: exclusive write of lock.P.claim; EEXIST: locked + lock still holds P: remove lock; create; remove the claim + lock gone or holds another PID: locked; remove the claim +``` + +```mermaid +sequenceDiagram + participant A as starter A + participant B as starter B + participant F as ROOT + Note over F: lock holds the stopped PID P + A->>F: read lock: P, stopped + B->>F: read lock: P, stopped + B->>F: link lock to lock.P.claim, or without links write it exclusively: created + B->>F: lock holds P: remove lock#59; create B's lock#59; remove the claim + A->>F: link lock to lock.P.claim, or without links write it exclusively: created + A->>F: lock holds B's PID + A->>A: locked#59; remove the claim +``` + +Chat ownership, D8 (a): +``` +ChatOwner, in the chat's custom data + session Claude Code session ID that connected the chat +``` + +``` +on connect by session s: owner = s +on any tool call by s: chats with owner = s only +on "/give CHAT N" by an admin or owner of the session's group: owner of CHAT = session N +on resume of s: its chats are shown again +``` + +## Model and effort + +Sources (https://code.claude.com/docs/en/hooks, https://code.claude.com/docs/en/settings, https://code.claude.com/docs/en/remote-control): +``` +value read from updated on +model SessionStart model (optional) PostModelSwitch to_model; Stop: the model of its answer in the transcript +effort effort.level of a turn hook the next turn hook; no event for an effort change +``` + +``` +on SessionStart(m): model = m +on PostModelSwitch(t): model = t +on Stop(answer): model = message.model of Claude's last transcript entry, once its text is answer; + up to 20 reads 100 ms apart of the last 1 MiB + 2 × bytes(answer); none for (decision 31) +on a turn hook(e): effort = e.effort.level, when given; turn hooks: UserPromptSubmit, Stop, PostModelSwitch (decision 31) +on a change of either: group short description = "MODEL · effort LEVEL" +``` + +```mermaid +flowchart LR + SS[SessionStart: model] --> T[POST /title] + PM[PostModelSwitch: to_model] --> R[POST /turn] + SP[Stop: transcript_path] --> TR[transcript tail: model of the answer] --> R + ST[UserPromptSubmit, Stop, PostModelSwitch: effort.level] --> R + T --> D[session group short description] + R --> D +``` + +Changing them from SimpleX, per the docs: +``` +route effect on the running session +model or effortLevel in settings files none: read once at session start +hook output none: no field sets them +a message in the session group none: a one-line "/" text is a command of the group, and Claude Code runs no command + from a prompt (decision 117) +Remote Control from the Claude app changes both +``` + +Model and effort change in the terminal or by Remote Control (D9). + +## Components + +```mermaid +flowchart LR + subgraph App[SimpleX app] + O[owners] + end + subgraph Host[computer] + CC[Claude Code session N] -- stdio MCP --> S[simplex-mcp session] + S -- Unix socket --> D[service] + D --> H[Claude profile] + D --> U[User profile] + SV[simplex-mcp serve, HTTP] --> A0[agent profile] + end + H -- Main group --> O + H -- session N group --> O + U -- session N group --> O + H <-- SimpleX --> P[peers] + A0 <-- SimpleX --> P +``` + +``` +process runs holds +simplex-mcp session one per Claude Code session, stdio tools, channel capability +service one per data root, Unix socket Claude and User profiles, actions +Claude inside the service Main group, session groups, owners, cards, chats with peers +User inside the service membership in every session group +simplex-mcp serve one per agent, HTTP 127.0.0.1 agent profile, control chat +``` + +## Trust model + +Set by the user on 2026-11-08 as the role model. It rewrites decision 17 and takes the place of decisions 62, 63, 70, 72, 73, 79, 80 and 82. + +The user's words: +- "Whoever is in the hub is the trusted user and should be able to have the same access to sessions as owner. It should be clearly stated when anybody is joining and invited, and on top of hub." +- "Whoever joins from hub, automatically joins as admin. Whoever joins via invitation, would be joining with the role assigned by admin+ in the session group. This way we decouple it from member origin, that is not visible in session group. And attach it to visible role. On every role change, Claude will be commenting on the member privileges." +- "yes, only admins and owners can send // and /! commands and approve tool calls"; members below admin send prompts: "yes, obviously". +- "I suggest we simply accept that all files are receivable, and if owners want to prohibit sending files, group has controls for it." + +``` +principal who trusted with +computer user any program running as the user on the computer the trust root: replaces the Main group and its owners at once (decision 113) + that runs Claude Code +hub member every member of the Main group, any role all sessions: joins each by /join N as admin +session approver an admin or owner of a session group, User excepted that session: prompts, the group's commands, approvals, tool use +session sender a moderator, member or author of a session group that session: prompts +observer a member of a session group with that role nothing: cannot send +peer anyone in Claude's other chats nothing: messages are data +``` + +Rules: +1. The Main group is the trust boundary for the sessions: its members are trusted with all sessions. Changes in the Main group, an owner reset included, do not change session groups (decision 78). +2. Rights in a session group follow the member's role there, never how the member joined. +3. Admins and owners send prompts and the group's commands, and approve tool calls. +4. Members and moderators send prompts; their `/` commands are refused. +5. Observers cannot send (SimpleX rule). +6. Members of the Main group who join by `/join N` become admins. Owners of the Main group are invited to each session group as owners (decision 110). +7. Members invited inside a session group get the role the inviter sets (SimpleX rule: admin or owner invites). +8. Claude's files reach the session group without approval. The group preference "Files and media", which owners change, is the control; the core enforces it. +9. Claude posts the member's rights at each join and at each role change. +10. Unchanged: the owner link reaches the person only; mode `host` needs a card; the approved mode lives in the session group; `/status` carries no link. + +An owner's approval or verdict in a session group, in the decisions and sections of this plan, is that of a session approver. + +```mermaid +flowchart LR + O[owner] -- own group link, or a contact invited --> M[Main group: hub members] + M -- invitation at the session start: owners, as owners --> G[group of session N] + M -- /join N: as admin, owners of M as owners --> G + X[person invited inside group N, with the role the inviter sets] --> G + G --> A[admins and owners: prompts, the group's / commands, approvals, tool use] + G --> P[moderators, members, authors: prompts, and one refusal for each / command] + G --> Q[observers: cannot send] + G --> F[files of reply: at once, under the group's preference Files and media] + G -- each join and role change --> R[Claude posts the member's rights] +``` + +Mechanics: +``` +approver of group N: an active member other than Claude and User, role admin or owner (decision 84) +prompter of group N: a member other than User whose role sends; the prompt rules in Session mirroring +Main group, at its creation: shortDescr = SHORT, description = WELCOME (decision 103) +Main group, at its load: the name and the commands, updated when they differ; shortDescr and description kept +on joinedGroupMember or connectedToGroupMember in the Main group: + the joiner among the members read again, a human: post "NAME joined. " + JOINED +a join raises one of the two: joinedGroupMember for a member who joined through the hub, + connectedToGroupMember for a member another member added +on "/join N" by member m: invitation through the Main group, role owner when m is an owner there, else admin (decision 85) +on joinedGroupMember, connectedToGroupMember or memberRole in group N, the member not User: + post RIGHTS(member) (decision 86) +RIGHTS(m): "NAME is a ROLE and " + RIGHTS of the role + "." + + " You can change role to observer to stop it: /'observer #G ID'" when the role sends and is not owner +RIGHTS of a role: admin, owner: can send prompts to Claude and the group's commands, and approve + tool use + moderator, member, author: can send prompts to Claude; the group's commands and approvals need + the role admin or owner + observer: can't send messages +on /observer #G ID by member s: #G not this group, no current member ID, ID Claude, s, a relay or pending: a reply + rank(s) < max(rank(admin), rank(member ID)): a reply + else: role of ID = observer; members read again; reply RIGHTS of the observer (decisions 81, 86, 93) +current member: status current or pending; an invited member who has not joined is none (decision 94) +rank: relay < observer < author < member < moderator < admin < owner, as the core orders them +a role change by Claude: no memberRole event; the reply of /observer is the post +Claude's profile update of a group: the group's current profile read from the chat database; only Claude's fields changed (decision 90) +on a one-line "/" text of a moderator, member or author in group N: + one reply, before the commands and the prompt (decision 91) +on another message of a member whose role sends: a prompt (decision 92) +group N, its description: "The Claude Code session N. Members send it prompts; admins and owners also send the group's commands + and approve tool use.", at the group's creation (decision 98) +reply: see Channel, reply +``` + +```mermaid +stateDiagram-v2 + [*] --> approver: /join N as admin, or an owner of the Main group as owner + [*] --> sender: invited inside the group as moderator, member or author + [*] --> observer: invited inside the group as observer + approver --> sender: role change in the app + sender --> approver: role change in the app + approver --> observer: /observer #35;G ID, or a role change in the app + sender --> observer: /observer #35;G ID, or a role change in the app + observer --> sender: role change in the app + observer --> approver: role change in the app + approver --> [*]: leaves or removed + sender --> [*]: leaves or removed + observer --> [*]: leaves or removed + note right of approver: admin or owner#58; prompts, the group's commands, approvals, tool use + note right of sender: prompts + note right of observer: cannot send +``` + +Each join and each transition between roles posts RIGHTS of the new role. + +Texts of the Main group: +``` +WELCOME 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. (decision 99) +JOINED They can join the group of any Claude Code session here, prompt Claude and approve its actions. (decision 99) +SHORT Everyone in this group can join the groups of your Claude Code sessions, prompt Claude and approve what it does. (decision 100) +UNKNOWN Unknown command. (decision 101) +``` + +Texts for Claude, which follow the trust model: the 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, ...`, and the `reply` tool's description `Sends a file to the members of the SimpleX group of this session, with text as its caption. Your final answer of each turn reaches them without this tool.` and `The file is sent at once, and the result has its item; the group's preference for files and media can refuse it, and the call then returns the refusal.` + +Set by the user on 2026-11-08, amended on 2026-11-10 by decision 117: +``` +unknown "/" command Unknown command. (decisions 71, 117) +``` + +Texts of the session groups, decided by judgement (decision 89): +``` +"/" from another role Only admins and owners of this group can send / commands. (decision 91) +approval from another role no reply, nothing performed, past the reply above only (decision 105) +no approver 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. +rights of owner NAME is an owner and can send prompts to Claude and the group's commands, and approve tool use. + (decisions 97, 117) +rights of 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' (decisions 97, 117) +rights of moderator, NAME is a member and can send prompts to Claude; the group's commands and approvals need the role +member, author admin or owner. You can change role to observer to stop it: /'observer #G ID' (decisions 97, 117) +rights of observer NAME is an observer and can't send messages. (also the reply to an accepted /observer) +``` + +Decided by judgement on 2026-11-09, as implemented: +``` +start notice none (decision 83) +/observer replies #G is not this group. / No member ID in this group. / NAME's role can't be changed. / + Your role does not let you change the role of NAME. (decision 81) +``` + +## Groups + +``` +group host members holds +Main group hub owners and other members QR link, invitation cards, /join, /sessions, owner reset +session N group hub Main group owners, invited by the hub, prompts, replies, action and tool-use cards of session N + as owners + Main group members who sent /join N, + as admins + people its admins and owners add, with + the role they set +``` + +``` +preference Main group session N group +history on on +direct messages on, role owner off +commands /join, /sessions /approve, /reject, /receive, /forward, /revoke, /pending, /list, /leave, /delete +name the plugin's main_group N · session title or project folder +``` + +Direct messages in the Main group are on for the owner role, because the core sends an invitation through a member connection only where direct messages are allowed (`docs/rfcs/2026-10-10-invite-member-via-group.md`). Joining needs a SimpleX app with chat version 22: v7.1.0 or later. + +Session group custom data: +``` +SessionGroupData + session session number + pending list of PendingConnection, optional + mode approved mode, optional: requests without it (decision 61) +PendingConnection + connId pending connection of a connect + at time it was recorded +``` + +``` +on session start (new id): create the session group; for each Main group owner: apiAddMemberViaGroup(group, main, owner, owner) +on owner joined Main group: for each open session: invite the owner as above +on "/join N" by member m: if session N exists: apiAddMemberViaGroup(group N, main, m, owner when m is an owner of the Main group, + else admin) (decision 85) +on message in group N: a command of the group, or a prompt of a member other than User (decisions 71, 84, 92); + approvals and the group's commands from admins and owners (decisions 84, 91) +on a join or role change in group N: the post of the member's rights (decision 86) +on session resume: reuse the group recorded in session.json +on connect with a pending connection c: pending += (c, now); entries older than one day dropped +on contactConnected or userJoinedGroup of c: the session whose pending has c, recorded in the last day: drop it; claim the chat +on connect to a known chat without an owner: claim the chat +``` + +Membership of the Main group in the session groups (rule 1 of the [trust model](#trust-model)): +``` +on a membership or role change in the Main group: the session groups stay as they are +on the replacement of the Main group (decision 113): the session groups and the roles of their members stay as they are (decision 78) +``` + +```mermaid +flowchart LR + R[reset-owners on the computer that runs Claude Code] --> M[old Main group deleted, new Main group and link] + R --> K[session groups kept, with their members' roles] + K --> P[members from the old Main group keep the rights of their roles] +``` + +```mermaid +sequenceDiagram + participant T as session's tools + participant H as hub + participant P as peer + T->>H: connect performed, pending connection c + H->>H: pending += c in the session group's data + T-->>T: connect returns connected: false + P->>H: accepts later: contactConnected, connection c + H->>H: pending -= c#59; chat owner = the session +``` + +Commands in a session group take no session prefix: `/approve 7`, `/receive @3 9`, `/leave #2`. + +### Session start + +```mermaid +sequenceDiagram + participant C as Claude Code + participant S as session N + participant H as hub + participant M as Main group + participant O as owner + C->>S: SessionStart + S->>H: POST /session + H->>H: create group "N · title" + H->>M: invitation through the owner's Main group connection + M->>O: card "Tap to join", for you only + O->>H: joins the session group +``` + +### Session identity + +Claude Code keeps the session server's `CLAUDE_CODE_SESSION_ID` from its spawn, changes the hooks' `session_id` on `/clear` and `/resume`, and with `--continue` may spawn the server with a startup ID (https://code.claude.com/docs/en/env-vars). Both run in one Claude Code process: `CLAUDE_PID` in the hooks, the parent PID of the session server (decision 36). + +``` +Entry of a session pid of its session server, time it was last seen +Title of a process pid to session ID, time + +on /title or /turn (id, pid), /session (id, pid): + alias of id -> that session + session.json for id: /title or /turn, an entry with that pid attached -> that session, no alias + otherwise -> id + /session only: no entry or title for pid: wait up to 10 s for a /title of pid + target = entry with that pid, attached or seen in the last 10 s + ?? title of pid in the last 10 s + target ?? id; target ≠ id: alias id → target, in aliases of the target's session.json +on /title (id, pid), no alias, no session.json for id, no entry or title for pid, or a held title of pid: + held; title of pid = id, now, its name; the waits of pid end; the reply at once; + the title resolves as above after a /session of pid, or after 10 s, while the service runs +on a service stop: the held titles into ROOT/titles.json; the next start takes each as a new /title +on /title (id, pid): after the entry exists: title of pid = id, now; the waits of pid end +on /session (id, pid) that creates a session: the name of the held title of id +on a new session.json: the aliases that already point to its ID +on /attach, /call, /permission (id): alias of id ?? id +on the service's start: aliases read from every session.json +on POST /turn refused with 409: the hook repeats it up to 15 times, 1 s apart, past the 10 s wait +``` + +```mermaid +sequenceDiagram + participant HK as hooks, CLAUDE_PID P + participant S as session server, parent P + participant D as service + Note over HK,D: /clear in session A + HK->>D: POST /title {id: B, pid: P} + D->>D: entry A has pid P and is attached: alias B → A + HK->>D: POST /turn {id: B}: session A + Note over HK,D: --continue: server with startup ID X, resumed session R + S->>D: POST /session {id: X, pid: P}: waits + HK->>D: POST /title {id: R, pid: P} + D->>D: title of P = R#59; the wait ends: alias X → R + D-->>S: session R + Note over HK,D: /resume R2 in session A#59; R2 has session.json + HK->>D: POST /title {id: R2, pid: P} + D->>D: entry A has pid P and is attached: session A, no alias + HK->>D: POST /turn {id: R2}: session A + Note over HK,D: later, claude --resume R2 in process Q + S->>D: POST /session {id: R2, pid: Q}: session R2, its own group + Note over HK,D: --fork-session with the title first, or /clear during a re-attach: new ID F, stored session A + HK->>D: POST /title {id: F, pid: P}: held, the reply at once + S->>D: POST /session {id: A, pid: P}: session A + D->>D: the held title resolves: entry A has pid P: alias F → A +``` + +### Runs that are not interactive + +Decisions 60 and 66: +``` +on CLAUDE_CODE_ENTRYPOINT sdk-cli, sdk-ts or sdk-py, or CLAUDE_CODE_SESSION_ATTENDED 0: + hooks: {} + session server: no service connection; every call: "This Claude Code run is not interactive, + so it has no SimpleX group; the SimpleX tools work in interactive sessions." +on SessionStart with CLAUDE_CODE_SESSION_ATTENDED 0, another entrypoint and CLAUDE_PID P: + hook: ensureService; POST /title {id, pid: P, project, config, unattended: true}; {} + service: unattended -= marks of 10 s ago and older (decision 77); unattended[P] = now; + a /session of P waiting for its title ends its wait +on /session of P, before and after the wait for its title: + unattended[P] in the last 10 s: 403 +on 403 of /session: the session server answers every call with the text above, + relays no permission request and registers no more +``` + +``` +variable set by Claude Code for values +CLAUDE_CODE_ENTRYPOINT hooks and MCP servers sdk-cli for claude -p, cli for an interactive session; + one set before the start is kept, except cli +CLAUDE_CODE_SESSION_ATTENDED hooks; an MCP server gets the value of 1, or 0 for a run nobody attends + the session whose command started the run +``` + +```mermaid +flowchart LR + E[hook or session server] --> A{CLAUDE_CODE_SESSION_ATTENDED 0} + A -- yes --> N[not interactive] + A -- no --> P{entrypoint sdk-cli, sdk-ts or sdk-py} + P -- yes --> N + P -- no --> I[interactive] +``` + +```mermaid +sequenceDiagram + participant HK as SessionStart hook, ATTENDED 0 + participant S as session server, ATTENDED 1 of the parent session + participant D as service + HK->>D: POST /title {pid: P, unattended: true} + D->>D: the marks of 10 s ago and older removed#59; P marked + S->>D: POST /session {pid: P}, before or after the mark + D-->>S: 403 + S->>S: every call: the text of a run that is not interactive +``` + +## Channel + +Session server capabilities: +``` +capability value +experimental.claude/channel {} +experimental.claude/channel/permission {} +tools {} +``` + +Service to session, lines on `/attach`: +``` +line sent when +{prompt: {text, from, item, file?}} a member's prompt arrives in the session group +{permission: {requestId, behavior}} an owner decides a tool-use card +``` + +Session to Claude Code: +``` +notification params +notifications/claude/channel content: text + meta.from: member name + meta.item: session group item ID + meta.file: path +notifications/claude/channel/permission request_id + behavior: allow | deny +``` + +Claude Code to session, then session to service: +``` +notification route +notifications/claude/channel/permission_request POST /permission {id, requestId, toolName, description, inputPreview} +``` + +New tool: +``` +tool input action +reply file, text? sends the file to the session group at once, text as its caption +``` + +`reply` (rule 8 of the [trust model](#trust-model), decision 87): +``` +on reply {file, text}: the file checked as for send + its message with the caption and the preview does not fit: tool error (decision 76) + send, with the caption and the preview, in both modes -> {item} + the core refuses it with "feature not allowed Files and media": + tool error FILES OFF (decision 102) + the core refuses it otherwise: tool error, the core's text +on Claude's profile update of the session group: from the group's current profile, only Claude's fields changed (decision 90) +``` + +```mermaid +stateDiagram-v2 + [*] --> refused: reply, the caption too long for a message with the file + [*] --> sent: reply, the group's preference allows the files of Claude's role + [*] --> refused: reply, the core refuses the file + sent --> [*] + refused --> [*] +``` + +Server instructions, added: messages in a `simplex` channel are the prompts of the members of the session's group; the final answer of the turn reaches them; `reply` sends them files. + +Protocol revision (decision 69): `initialize` negotiates 2025-11-25; `server/discover` gets `Method not found`. +```mermaid +sequenceDiagram + participant CC as Claude Code 2.1.319 + participant S as session server + CC->>S: server/discover, revision 2026-07-28 + S-->>CC: Method not found + CC->>S: initialize, revision 2025-11-25 + S-->>CC: 2025-11-25, capabilities claude/channel and claude/channel/permission + CC->>CC: the channel registered +``` + +Attachment of the session server (decision 37): +``` +on the end of /attach, or a failed start: not closed and not another protocol: one timer, start again after delay +on the timer: delay = min(2 × delay, 30 s); start +on a successful start: delay = 1 s +on stdin closed: closed; the retry timer cleared +``` + +```mermaid +stateDiagram-v2 + [*] --> connecting: start + connecting --> attached: /session, /attach + connecting --> waiting: failure + attached --> waiting: /attach ends + waiting --> connecting: delay passed, 1 s doubling to 30 s + connecting --> [*]: another protocol + waiting --> [*]: stdin closed + attached --> [*]: stdin closed +``` + +## Session mirroring + +Hooks of the plugin (https://code.claude.com/docs/en/hooks), all with `"async": true`: +``` +hook input used route +UserPromptSubmit prompt, prompt_id, POST /turn {id, pid, at, prompt, typed, effort} + transcript_path, effort.level typed: the prompt's transcript entry (decision 121) +Stop last_assistant_message, POST /turn {id, pid, at, answer, model, effort} + transcript_path, effort.level model: of the answer's transcript entry (decision 31) +PostModelSwitch to_model, effort.level POST /turn {id, pid, at, model, effort} +``` + +`pid` is `CLAUDE_PID`; `at` is `performance.timeOrigin`, the start time of the hook process. The hook cuts a prompt or an answer over 250,000 characters there, ending with `…` (decision 51), starts the service when none runs, and repeats a turn refused with 409 up to 15 times, 1 s apart (decision 36). + +``` +Turn record + at start time of a UserPromptSubmit hook + item the pushed prompt it matched, or null +Pushed prompt + text, item, at + quoted an answer without an earlier turn record quoted it + +on a message m in group N: one-line "/" text from a member who is neither an admin, an owner nor User: + delivery = delivery then the reply of decision 91 + one-line "/" text: a command of the group, queued; + from User: dropped (decision 74); + a text outside its requests: reply "Unknown command." (decisions 71, 117) + else: delivery = delivery then prompt(m) (decision 45) +prompt(m): from User: nothing (decision 79) + else: deliver(m), also a text that starts with "!" (decision 117) +the role of m's member: its role in group N, from the message's member +deliver(m): N has no attachment: wait for one until 30 s after the service start (decision 43) + attached: receive its file in 10 min, or reply that it was not received + N has no attachment now: reply to m "Session N is not running." + else: pushed += (m.text, m.item, now), at most 20; push {prompt} +on POST /turn, before any await: + prompt p or answer a, at: end open tool-use cards created before at + answer a, also empty, at: earlier = turn records with at below at; turns -= earlier + quoted = item of the newest earlier + ?? the oldest pushed not quoted, marked quoted; it stays in pushed + answeredAt = max(answeredAt, at) + prompt p, at: matched = pushed (T, I) with a channel tag of T, I in p, or T = p pushed in the last 60 s + at not below answeredAt: turns += (at, oldest matched ?? null) (decision 39) + pushed -= matched +on POST /turn model or effort: a changed value: description in memory and session.json +on POST /turn prompt p: nothing matched; p not blank, not only channel tags of this server, not a one-line "/" command: + User posts parts(p) (decision 35) +on POST /turn answer a, not blank: Claude posts parts(a, quoted), quoting quoted when fits(first character of a, quoted) +then, also after a failed post, a changed value: the group short description (decisions 54, 58) +Claude's post with a quote: the core refuses the quote, or the post as largeMsg: the same post without it (decision 50) +parts(t, q): the longest runs of whole characters of t, each with fits(run, q for the first run), + each searched among the next 15602 characters (decision 75) +fits(text, q): 600 + bytes of JSON [content, fileName, quote of q, mentions] <= 15602, as for send (decision 33) +channel tag of T, I: \nT\n +``` + +A UserPromptSubmit prompt holds the channel tags of the prompts of its turn; one turn can hold several. + +Parts of a post (decision 33): +```mermaid +flowchart LR + T[answer or terminal prompt] --> Q{a quote, and it fits with the first character} + Q -- yes --> F[first part: the longest run that fits with the quote] + Q -- no --> N[first part: the longest run that fits without a quote] + F --> R[each next part: the longest run that fits without a quote] + N --> R +``` + +Quotes by hook start time (decision 39): +```mermaid +sequenceDiagram + participant S as Stop hook of turn 1, at 2 + participant U as UserPromptSubmit hook of turn 2, at 3 + participant D as service + Note over D: turns: (1, prompt 1) + U->>D: POST /turn {at: 3, prompt 2}: turns += (3, prompt 2) + S->>D: POST /turn {at: 2, answer 1}: quotes prompt 1#59; turns: (3, prompt 2) + Note over D: the Stop of turn 2, at 4, quotes prompt 2 +``` + +Stop request before the prompt request of its turn (decision 39): +```mermaid +sequenceDiagram + participant S as Stop hook, at 2 + participant U as UserPromptSubmit hook, at 1 + participant D as service + Note over D: pushed: prompt 42#59; turns: none + S->>D: POST /turn {at: 2, answer}: quotes 42, marked quoted, kept in pushed + U->>D: POST /turn {at: 1, prompt with the tag of 42}: matches 42#59; User posts nothing +``` + +``` +UserProfile + folder ROOT/_user + name User + contact Claude, connected once at the first start: the contact of the connection of Claude's invitation + groups every session group, added by Claude through the contact, joins automatically + visible to session group members only +``` + +Claude ignores User's messages as prompts and commands: the hub drops the messages of the member of its contact marked `simplexMcpUser`, read at its start (decisions 74, 79). + +A prompt to a session started without the channel flag is dropped by Claude Code; the hub cannot detect it. + +Files: a member's file in a prompt is received by the hub without a card into `ROOT/_sessions//files/group/`; `meta.file` is its path. `reply` with `file` sends it to the session group under the refused-path rules of `send`. + +### Prompt flow + +```mermaid +sequenceDiagram + participant O as member + participant H as hub + participant D as service + participant S as session N + participant C as Claude Code + O->>H: message in session N's group + alt one-line "/" text from a moderator, member or author + H->>O: after the earlier messages, the reply of decision 91 + else one-line "/" text + H->>O: the command's reply, or "Unknown command.", nothing for User + else another message + H->>H: after the earlier messages of session N + alt from User + H->>H: nothing + else a prompt, also one that starts with "!" + opt no attachment, within 30 s of the service start + H->>H: wait for session N to attach + end + opt attached, a file in the message + H->>H: receive the file, up to 10 min + end + alt session N has no attachment + H->>O: reply "Session N is not running." + else + H->>H: pushed += the prompt + H->>D: prompt for N + D->>S: {prompt} on /attach + S->>C: notifications/claude/channel + C->>D: UserPromptSubmit hook: POST /turn {prompt with the channel tag} + D->>H: turn prompt = the matched pushed prompt#59; not posted by User + C->>C: turn ends + C->>D: Stop hook: POST /turn {answer, at} + D->>H: end tool-use cards created before at#59; quote the newest turn record before at#59; post the answer in parts + H->>O: answer, quoting the prompt of its turn + end + end + end +``` + +### Tool-use approval + +```mermaid +sequenceDiagram + participant C as Claude Code + participant S as session N + participant D as service + participant H as hub + participant O as owner + C->>S: permission_request (abcde, Bash, preview) + S->>D: POST /permission + D->>H: new action, tool "permission" + H->>O: card in session N's group: "Run Bash?" /approve K /reject K + O->>H: /approve K + H->>D: verdict allow + D->>S: {permission} on /attach + S->>C: notifications/claude/channel/permission allow +``` + +``` +PermissionAction + number action number + session session number + requestId five letters from Claude Code + toolName + description + inputPreview + state pending | performing | done | rejected | expired + decidedBy owner name +``` + +``` +state meaning next +pending asked performing | rejected | expired +performing allowed done +done allowed final +rejected denied final +expired ended final +``` + +``` +on permission_request(r): action = permission(session, r), mode requests; post card in the session group +on /approve K by owner: if action K pending: state = performing; push {permission: allow}; state = done +on /reject K by owner: if action K pending: state = rejected; push {permission: deny} +on a prompt or Stop with hook time at: for each pending permission created before at: state = expired; edit card "Ended." +on session detached: for each pending permission of the session: the same +on state done, rejected, expired: remove the action from the session's actions +on list by the session: its actions without those of tools permission and mode (decision 68) +``` + +```mermaid +stateDiagram-v2 + [*] --> pending: permission_request + pending --> performing: /approve K, allow pushed + performing --> done + pending --> rejected: /reject K, deny pushed + pending --> expired: later prompt or Stop, detach: Ended.#59; expiry: Expired. + done --> [*]: removed + rejected --> [*]: removed + expired --> [*]: removed +``` + +The first answer, at the terminal or in the group, applies; Claude Code closes the other. + +### Mode host + +``` +on /session with approve a: requested = a + a = requests: pending mode cards end ("Ended."); hostDeclined = false; mode = requests, in the session group's data + a = host: ask +on a membership event of the session group: ask +ask: requested = host, not hostDeclined, mode = requests, an approver in the group, + no pending mode card: post the mode card +on the mode card rejected: requested = none; hostDeclined = true, in session.json +on the mode card expired: requested = none +on the mode card approved: mode = host, in the session group's data (decision 61) +on the session's open: mode = the session group's data, or requests +``` + +Main group link on the socket (decision 61): +``` +route owner field +POST /title {owners, link?}: the hook shows the link +GET /link {owners, link?}: simplex-mcp link reads it while the Main group has no owner +GET /status {owners} +POST /session {owners} +``` + +```mermaid +flowchart LR + HK[SessionStart hook] -- POST /title --> L[owners and link] + LK[simplex-mcp link] -- GET /status --> O[owners] + LK -- no owner: GET /link --> L + S[session server] -- GET /status, POST /session --> O +``` + +```mermaid +stateDiagram-v2 + [*] --> asking: /session host, an approver + asking --> host: approved + asking --> declined: rejected, hostDeclined in session.json + declined --> declined: /session host, also after a restart: no card + declined --> requests: /session requests: hostDeclined cleared + requests --> asking: /session host + host --> requests: /session requests +``` + +```mermaid +sequenceDiagram + participant S as session server + participant H as hub + participant O as owner + S->>H: POST /session {approve: host} + H->>H: requested = host#59; no approver yet + O->>H: joins the session group + H->>O: mode card + O->>H: /approve N + H->>H: mode host +``` + +## Launch + +``` +state command +listed by Anthropic claude --channels plugin:simplex@simplex-chat +before the listing claude --dangerously-load-development-channels plugin:simplex@simplex-chat +Team and Enterprise plans an admin adds simplex@simplex-chat to allowedChannelPlugins +``` + +The development flag works in interactive sessions only. Without either flag the plugin works without prompts and tool-use relay. + +Shared settings (decision 120): +``` +settings user, --settings or managed: + extraKnownMarketplaces simplex-local: source directory, PATH absolute + enabledPlugins simplex@simplex-local: true +PATH .claude-plugin/marketplace.json: plugin simplex, source ./plugin + plugin/: the unpacked package, nothing installed +each start claude --dangerously-load-development-channels plugin:simplex@simplex-local + --channels: simplex@simplex-local in the organization's allowedChannelPlugins +data folder one per machine or container: ~/.simplex-mcp, or SIMPLEX_MCP_HOME of its environment; + sessions and the service lock are matched by process IDs of that machine or container +``` + +```mermaid +flowchart LR + S[shared settings] --> K[marketplace simplex-local: PATH] + K --> P[PATH/plugin: the unpacked package] + F[channel flag at each start] --> C + P --> C[Claude Code session] + C --> D[data folder of this machine or container] + D --> M[its own service and Main group] +``` + +## Pull request + +```mermaid +flowchart LR + K[sh/mcp-known, 49 commits] --> M[merge of master] + M --> G[session groups, owner rules] + G --> C[channel, 0.3.0] + C --> P[PR against master] + P -. replaces .-> X[#7810] + P --> V[page presenting the PR, checked against the diff by an independent reviewer] +``` + +``` +branch ep/mcp-plugin, from sh/mcp-known, in the agents' fork +base master +commits #7810's 49 commits + merge of master: serve, register and HTTP kept; 0.2 features in session groups + one Claude profile, session groups and owner rules: decisions 6, 11, 13, 17-23 + channel and mirroring: decisions 7, 9, 12, 14, 24-26, reply tool, version 0.3.0 +``` + +Size estimate, source lines written on top of `sh/mcp-known`, without tests: +``` +part estimate +merge, session groups, owner rules 750 +channel and mirroring 450 +``` + +`serve` and its end-to-end tests keep passing. `build.yml` publishes 0.3.0 after the merge.