simplex-orchestrate/CLAUDE.md

SimpleX Orchestrate — project notes for Claude

Goal: a web-managed orchestrator that runs the official SimpleX binaries (instead of re-implementing bot logic against the FFI libsimplex SDK, as the older simplex-manager prototype did). The manager spawns/supervises real SimpleX processes, drives the interactive ones over WebSocket, and reads the autonomous ones' output.

Reference checkout: ./simplex-chat/ (cloned from https://github.com/simplex-chat/simplex-chat). All facts below are taken from that repo's own docs — cited inline. There is no CLAUDE.md / AGENTS.md in the upstream repo; the authoritative interface docs are:

• simplex-chat/bots/README.md — bot architecture & WebSocket API
• simplex-chat/bots/api/COMMANDS.md, EVENTS.md, TYPES.md — full command/event/type reference
• simplex-chat/docs/CLI.md — terminal client / DB / server flags
• simplex-chat/apps/*/README.md + src/.../Options.hs — the official bot binaries
• Official TypeScript SDK: simplex-chat/packages/simplex-chat-client/typescript/

---

Two integration patterns (this is the core design decision)

1. Interactive accounts → drive the CLI over WebSocket (bots/README.md)

• Run the terminal client as a local WebSocket server: simplex-chat -p 5225
• Our process connects over WebSocket and sends JSON commands / receives events.
• This is how custom bots (TS/Python/Rust) and our manager talk to a profile.
• Same command strings as the app's Settings → Developer tools → Chat Console.

2. Autonomous official bots → run the prebuilt Haskell binary directly

• simplex-directory-service and simplex-broadcast-bot are standalone executables built on the chat core. They run their own logic, with their own DB + config, no WebSocket.
• The manager's job for these is lifecycle (spawn/stop/monitor/logs) + reading their output.
• Use these instead of reimplementing directory/broadcast in Python — they're battle-tested and include captcha, moderation, approval, periodic re-checks, website generation, etc.

---

WebSocket protocol (pattern 1) — bots/README.md

• simplex-chat -p <port> starts the WS server. localhost only, NO authentication — keep the bot process on the same machine and firewall the port. Messages are unencrypted.
• Command: {"corrId":"<unique>", "cmd":"<command string>"}
• Response: {"corrId":"<same>", "resp":{"type":"<tag>", ...}} (matched by corrId)
• Event: {"resp":{"type":"<tag>", ...}} (no corrId — connections, received messages, etc.)
• NewChatItems arrives both as a command response (after APISendMessages) and as an event.
• Parser must ignore unknown event types / union tags / extra fields (forward-compat rule).
• Minimal bot loop: handle NewChatItems event → reply with APISendMessages.
• Network usage per command is documented: no / interactive / background.

Per-profile databases — docs/CLI.md

• simplex-chat -d <prefix> → creates <prefix>_v1_chat.db and <prefix>_v1_agent.db.
• Default data dir ~/.simplex (%APPDATA%/simplex on Windows).
• One process = one DB prefix. A single DB can hold multiple bot profiles via /create bot [files=on] <name> [<bio>], but the simple model is one process per profile.
• SMP servers: -s smp://<fp>@host. Tor: -x or --socks-proxy=:9050. simplex-chat -h for all.

Bot profile setup — bots/README.md (needs app/CLI v6.4.3+)

• Mark a profile as a bot: peerType: "bot". Set via:
  • CLI flags --create-bot-display-name, --create-bot-allow-files on first start, or
  • /create bot [files=on] '<name>' [<bio>], or
  • APIUpdateProfile (also sets command menus).
• Command menus: /set bot commands '<label>':/'<keyword>[ <params>]', '<label>':{...nested...} (e.g. directory's 'Show your groups':/list). Per-contact overrides via APISetContactPrefs.
• Business address (support): a special group chat per connecting customer; inherits the bot's preferences/commands. See docs/BUSINESS.md.

---

Official bot: Directory service — apps/simplex-directory-service/ (Directory/Options.hs)

Run the simplex-directory-service binary; it manages registration + search and writes the website files itself. Replaces the Python directory reimplementation in the old prototype.

Key CLI options:

• --super-users CONTACT_ID:DISPLAY_NAME,... (required) — who can approve/manage listings
• --admin-users CONTACT_ID:DISPLAY_NAME,... — directory managers
• --owners-group GROUP_ID:DISPLAY_NAME — owners of listed groups auto-invited
• --directory-file PATH — append-only log holding directory state
• --web-folder PATH — where static web assets / group listing files are written (this is what feeds the directory website; our old web/<bot>/data/listing.json was a hand-rolled stand-in)
• --service-name "SimpleX Directory" — bot display name (default shown)
• --captcha-generator EXE / --voice-captcha-generator EXE — anti-spam
• --blocked-words-file / --blocked-fragments-file / --blocked-extenstion-rules / --name-spelling-file / --profile-name-limit — moderation
• --link-check-interval SECONDS (default 1800) — periodic re-check of public group links
• --run-cli — interactive CLI mode
• --migrate-directory-file <check|import|export|listing> — listing = saveGroupListingFiles regenerates the website listing files from the log
• plus core chat options (DB file, SMP servers, Tor) shared with the CLI
• Registration flow = owner adds the bot to their group; listing stays pending until a super-user approves (matches what we scoped for the prototype).

Official bot: Broadcast — apps/simplex-broadcast-bot/

• --display-name, --publishers CONTACT_ID:DISPLAY_NAME,..., --welcome, --prohibited (+ core DB/SMP options). Re-broadcasts messages from publishers to all connected contacts.

Other official bot apps

• apps/simplex-bot / simplex-bot-advanced — minimal Haskell bot examples
• apps/simplex-support-bot — support/business example
• apps/simplex-chat — the terminal CLI itself

---

Getting the binaries

• Install script: curl -o- https://raw.githubusercontent.com/simplex-chat/simplex-chat/stable/install.sh | bash → simplex-chat on PATH (CLI only).
• Prebuilt binaries: GitHub Releases (per stable version).
• Build from source (docs/CLI.md): GHC 9.6.3 + cabal 3.10.1.0, or DOCKER_BUILDKIT=1 docker build --output ~/.local/bin .. Bot apps build via cabal install <exe> (e.g. simplex-directory-service, simplex-broadcast-bot).
• Build the stable branch, not master.

Proposed orchestrator architecture (to flesh out)

• Manager (web UI + supervisor) keeps a registry of profiles. Each profile has a kind:
  • cli (interactive: user/echo/support/custom) → spawn simplex-chat -p <port> -d data/<name>, connect WS, proxy commands; one port per profile.
  • directory → spawn simplex-directory-service with --directory-file, --web-folder, --super-users, DB; supervise + serve its web folder.
  • broadcast → spawn simplex-broadcast-bot with publishers/welcome; supervise.
• Web frontend talks only to the manager; the manager owns process lifecycle, port allocation, log capture, and (for directory) serving the generated web folder.
• Security: bind all CLI WS ports to localhost; never expose unauthenticated WS publicly.