CoralSwarm Connect

Connect the CoralSwarm MCP and turn on automatic, in-session capture of your work into your ocean — at natural checkpoints during the session, not only when it ends. Ships for Claude Code, Cursor, and Codex. Enable the plugin in one manager; leaving two copies enabled will fire SessionStart twice (the kernel no-ops the duplicate).

Install

There are two levels. The plugin gives you the MCP tools plus the capture hooks and the bundled skill; the raw MCP URL gives you the tools only, and works in any MCP client.

coralswarm-connect@coralswarm-connect is not a typo: the first half is the plugin, the second is the marketplace this repo publishes (both are named coralswarm-connect — see .claude-plugin/marketplace.json). The same two commands work from a shell as claude plugin marketplace add … / claude plugin install ….

After any of these, authenticate: in Claude Code run /mcp and Authenticate on the coralswarm server; in Cursor use /mcp login or the mcp_auth prompt. Auth is OAuth (Clerk) with dynamic client registration — there is no API key to paste and nothing to put in a config file.

The MCP URL must be that literal string. Cursor rejects a fly.dev resource that does not match the server's protected-resource metadata.

CoralSwarm Connect is not listed in any client's built-in plugin or connector directory yet. The paths above are the ones that work today. This repo also ships server.json for the official MCP Registry under the name com.coralswarm/coralswarm; it is published by a release tag (see Releasing), so treat a registry listing as present only once a tag has shipped.

Do not run scripts/install.mjs when the plugin is enabled — that would register the same events a second time in settings.json.

Public plugin repo. This repository is the marketplace source. The product backend still lives in CoralSwarm/coralswarm. Refresh with /plugin marketplace update coralswarm-connect.

One-time trust + OAuth. A plugin-provided MCP server still requires you to approve the server (trust prompt) and complete OAuth via /mcp the first time — the plugin declares the server, it can't pre-authorize your account.

What the plugin sets up

1. MCP connection (.mcp.json) — declares the CoralSwarm MCP server (HTTP transport) so its tools (list_oceans, recent_activity, ask_ocean, search_atoms, get_reef, add_context, list_sessions, …) are available once you authenticate.

   The plugin .mcp.json is the literal URL https://api.coralswarm.com/mcp (hosts do not expand ${VAR:-default}, and Cursor requires a byte-exact match with the server's protected-resource metadata). There is no separate org address; the same URL serves your personal ocean AND every organization you belong to. Staging or a local backend is a user-level MCP override (~/.cursor/mcp.json / claude mcp add), not a plugin edit.

   Personal vs. organization is chosen IN-BAND, not by URL: if you belong to ≥1 organization, the connection starts restricted to one tool, list_tenants. Call it, then call select_tenant with the org you want (or leave it unselected to work in your personal ocean) — that unlocks the rest of the tools, scoped to whichever plane you picked. Calling select_tenant again, any time, switches — no new session required, unlike the old per-URL setup.

   Want both at once? Register this SAME URL a second time under its own server name (see Manual install below) and call select_tenant independently on each registration — each gets its own OAuth connection and its own remembered selection. You get both tool sets in one session, distinguished by server name.

2. Capture hooks (hooks/hooks.json), all firing during a session:

   • SessionStart → primes the agent to load relevant ocean context and to save each milestone as it happens, and emits sanitized session metadata (project key, git branch, credential-stripped remote, repo path, hostname, harness version) for the agent to stamp onto every save. A hybrid inventory line lists registered capture events vs those observed this session — hosts that never fire a given event stay dark (degrade in public) instead of blocking the turn.
   • UserPromptSubmit → a debounced reminder (about every 15 min of active work) to save recent progress, plus a one-line notice when the git branch changes mid-session. This is the recurring, mid-session capture.
   • PreCompact → flushes unsaved work into the ocean right before the conversation is compacted, so nothing is lost.
   • Stop → a final backstop (debounced ~10 min).
   • PostToolUse (matcher add_context) → stamps a local activity ledger every time an add_context save runs (Claude mcp__…add_context, Cursor MCP: …/add_context / CallDynamicTool), powering deterministic recovery of crashed sessions (see below). Every event is dispatched through hooks/run.mjs.

3. The coralswarm-connect skill — say "onboard coralswarm" and the bundled skill walks through the same setup conversationally (useful if you installed the MCP some other way, or to verify the round-trip).

Plugin installs always get the Stop backstop. The manual installer (scripts/install.mjs) exposes a --no-stop flag to omit it, but a plugin's hooks.json is static — it can't take install-time flags — so the Stop hook is always included here. It's debounced (~10 min per session), so it stays quiet; PreCompact and the mid-session nudges do most of the work.

The hooks reference ${CLAUDE_PLUGIN_ROOT}, which Claude Code, Cursor, and Codex expand to this plugin's install directory. Every event's command is node "${CLAUDE_PLUGIN_ROOT}/hooks/run.mjs" (Cursor ignores a separate args array). Hook scripts write per-session debounce/branch/primer state under ~/.coralswarm/state/ (shared with the manual-install path). The primer runs once per session_id so a dual Claude+Cursor install does not inject twice.

Session metadata & the credential-stripping guarantee (Phase 2)

The SessionStart primer reads the hook stdin payload and collects best-effort session metadata — unavailable fields are omitted and the hook keeps running if git/env is missing. Saving a session checkpoint still requires a session_id; optional provenance can be omitted. The git remote is run through hooks/project-key.mjs, a byte-for-byte parity port of the backend v1 normalizer (backend/src/project_key.rs), which unconditionally strips embedded credentials before the value is ever injected into the prompt — a token-bearing remote like https://x:ghp_secret@github.com/a/b.git is only ever emitted as github.com/a/b. These values are best-effort provenance; the server re-normalizes and re-validates everything.

Agent sessions — background runs, bots and their subagents

A bot or background worker saves an agent session by passing both a stable session_id and session_kind="agent" to add_context, with agent_name and its actual client platform. Keep the same session ID across topics and use a new checkpoint ID for each milestone. session_kind alone leaves the save as a note.

In a supported harness, naming the agent is enough: set CORALSWARM_AGENT_NAME (or run under the Claude Agent SDK, which names itself via CLAUDE_AGENT_SDK_CLIENT_APP) before startup, and the primer emits agent_name alongside the harness's session ID — the server infers session_kind=agent from that name's presence. Set CORALSWARM_SESSION_KIND=agent explicitly (plus CORALSWARM_PLATFORM, CORALSWARM_TASK) only for a harness the server can't otherwise identify. Custom bots call MCP directly and keep session/checkpoint IDs in their run state. See the save contract and examples for standalone notes, coding conversations, bot checkpoints, retries, and confirming what was saved. See agent setup for environment variables and linking each subagent's own session to its parent.

Deterministic reconciliation — how crashed/killed sessions get recovered

The nudges above are model-driven: they only help if the agent acts on them. Three ways work still slips through:

• a hard kill — SIGKILL, a closed laptop, an OOM — fires no exit hook at all, so nothing can flush at death;
• the agent ignores a mid-session nudge;
• a long single turn does a lot of work between debounced reminders.

Because a dead session can't write a "you have unsaved work" marker at death, the plugin writes a heartbeat continuously during normal operation and reconciles at the start of the next session. It keeps a tiny per-session record — paths and timestamps only, never transcript content — at ~/.coralswarm/state/sessions/{session_id}.json: