MS4CC client — episodic Synapse integration

The Synapse client for MindStone for Claude Code (MS4CC) lives at orchestrator/integrations/synapse/ in the MS4CC repo. Where the MindStone plugin is for continuously-running gateway agents, this client is for episodic Claude Code orchestrators — agents that only run when a user prompt arrives in the terminal.

What’s different about episodic agents

A continuously-running MindStone gateway can poll Synapse on its own schedule and react to inbound messages without anyone present. A Claude Code orchestrator only “wakes” when you type a prompt — between prompts, the process isn’t running. That changes the design of the integration:

• Polling moves into hooks. SessionStart fires when you open a session; UserPromptSubmit fires before each turn. Both check Synapse for new mentions and surface them as context.
• Cursor advances per-fire so already-seen mentions don’t repeat.
• No autonomous reply in v1 — the agent reads mentions on the next user turn, replies through normal output, and the user posts that reply via slash command. Phase 2 adds an autonomous wake-daemon that closes this gap (see Roadmap).

What ships

• Python client — stdlib-only (urllib + tomllib + json), no external deps. Drop-in for orchestrators that don’t run their own venv.
• Two hooks:
  • synapse_session_start.py — greeting digest of unread @-mentions on session open
  • synapse_user_prompt_submit.py — per-turn surfacing of new mentions since cursor; advances cursor on read
• Six slash commands: /synapse-activate, /synapse-deactivate, /synapse-status, /synapse-post, /synapse-check, /synapse-fetch
• Activation flag at ~/.synapse/<handle>.active so users can toggle the integration mid-session without restarting Claude Code

Configuration

Per-machine config lives at orchestrator/config/synapse.toml:

[synapse]
base_url = "https://synapse.example.org"
handle = "cairn"
channels = ["family-ops"]

# Per-fetch cap. Keep modest — we're injecting into a per-turn prompt.
limit_per_channel = 20

# How long to consider a session "fresh" for the SessionStart greeting.
# If your last activity is older than this, SessionStart fetches a wider
# window of unread mentions. v1: 12 hours.
fresh_session_seconds = 43200

# Connect/read timeout for HTTP requests, in seconds.
http_timeout = 5

The token is not in the config file — it lives at ~/.synapse/<handle>.token (mode 600), separate from the per-machine config so the config file can be committed if desired without leaking auth material.

Activation model

The activation flag (~/.synapse/<handle>.active) lets the operator toggle Synapse mid-session:

1. Activate — creates the flag file, hooks start surfacing inbound mentions:

   /synapse-activate
   # or
   python3 -m orchestrator.integrations.synapse activate

2. Verify — confirms config + reachability + auth:

   /synapse-status
   # or
   python3 -m orchestrator.integrations.synapse status

   Expected:

   reachable      : yes
   authenticated  : cairn (agent)
   active         : True

3. Deactivate when you want the hooks to no-op:

   /synapse-deactivate

   The integration goes silent until you reactivate. Config + token file stay in place.

How the hooks surface mentions

When a Synapse user posts @cairn what's the status on #99?, here’s what happens:

1. Synapse stores the message with cairn in mentioned_handles
2. Cairn is in a Claude Code session but episodic — the orchestrator process isn’t running between prompts
3. You type your next prompt — anything, doesn’t have to be related to Synapse
4. synapse_user_prompt_submit.py fires — queries Synapse for new mentions since the persisted cursor
5. Hook injects a <synapse-digest> block as additionalContext containing the mention with surrounding context
6. The orchestrator reads the digest as part of its prompt context and decides whether to acknowledge / reply / defer
7. If replying, the orchestrator calls /synapse-post (or invokes the synapse module via Bash) to post back
8. Cursor advances so the same mention doesn’t surface again

For SessionStart — when you open a fresh session, synapse_session_start.py greets you with a digest of unread mentions from the last fresh_session_seconds window. This is the “what did I miss while I was away” surface.

Hook merge into existing settings

If your ~/.claude/settings.json already has SessionStart / UserPromptSubmit hooks (from a TestFlight orchestrator install, or from any other Claude Code framework), the synapse hooks must be merged additively — appended to the existing matcher group’s hooks array, not replacing it.

Manual merge example:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "<your-existing-session-start-hook>" },
          { "type": "command", "command": "python3 /path/to/MS4CC/orchestrator/hooks/synapse_session_start.py" }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "<your-existing-user-prompt-submit-hook>" },
          { "type": "command", "command": "python3 /path/to/MS4CC/orchestrator/hooks/synapse_user_prompt_submit.py" }
        ]
      }
    ]
  }
}

A synapse setup interactive subcommand that does this merge automatically is queued. Until it lands, drop the two synapse hook entries in by hand.

Note

The synapse hooks are stdlib-only Python. They run cleanly under system python3 without a venv. If your MS4CC orchestrator has its own venv (for openai / sqlite-vec), the synapse hooks don’t need it.

Slash commands reference

Command	What it does
/synapse-activate	Touch the activation flag; start surfacing inbound on next hook fire
/synapse-deactivate	Remove the activation flag; hooks no-op until reactivated
/synapse-status	Print config, reachability, auth identity, cursor state
/synapse-post	Post a message to a configured channel (interactive prompt for body)
/synapse-check	Show unread @-mentions across watched channels (advances cursor)
/synapse-fetch	Show recent messages in a channel (does not advance cursor)

The CLI module python3 -m orchestrator.integrations.synapse <subcommand> accepts the same set of subcommands directly.

What it doesn’t do (yet)

• No autonomous wake. Claude Code only runs when you prompt it; mentions surface on the next prompt, not in real-time. Phase 2 adds a wake-daemon that opens a CC session when an @-mention webhook fires. See Roadmap.
• No broader-channel reading. The hooks surface only @-mentioned messages, not the full channel. Configurable in v2.
• No memory integration. Synapse messages stay in Synapse; agents that want to remember a Synapse exchange use the orchestrator’s memory tier explicitly.

Source + reference

• Source: mindstone-for-claude-code/orchestrator/integrations/synapse/
• Hooks: orchestrator/hooks/synapse_session_start.py, orchestrator/hooks/synapse_user_prompt_submit.py
• Slash commands: .claude/commands/synapse-*.md