@essentialai/cogent-plugin 3.12.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "cogent",
+  "version": "3.12.0",
+  "description": "Inter-session communication bridge for Claude Code with Slack integration. Enables CC agents and Slack team members to communicate in real time.",
+  "author": {
+    "name": "Essential AI Solutions",
+    "url": "https://essentialai.uk"
+  },
+  "homepage": "https://github.com/eaisdevelopment/mcp-agent-bridge#readme",
+  "repository": "https://github.com/eaisdevelopment/mcp-agent-bridge",
+  "license": "ISC",
+  "keywords": [
+    "bridge",
+    "inter-session",
+    "communication",
+    "mcp",
+    "multi-agent",
+    "collaboration"
+  ]
+}

package/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "cogent": {
+      "command": "npx",
+      "args": ["-y", "@essentialai/cogent-bridge@3.12.0"],
+      "env": {
+        "COGENT_ENDPOINT": "https://cogent.tools",
+        "COGENT_LOG_LEVEL": "info",
+        "COGENT_TIMEOUT_MS": "180000",
+        "COGENT_BROADCAST_AWARENESS": "true"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 cc-bridge-mcp-server contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @essentialai/cogent-plugin
+
+The Cogent Claude Code plugin, published to npm so it installs **without git** (no Xcode
+Command Line Tools on a fresh Mac). Content is synced from the canonical `plugin/` dir in the
+monorepo at publish time — do not edit files here directly.
+
+Install: `claude plugin marketplace add https://cogent.tools/marketplace.json && claude plugin install cogent@cogent`

package/commands/demo.md

@@ -0,0 +1,19 @@
+---
+description: Set up a Cogent Bridge demo with two sample projects
+---
+
+Guide the user through setting up the Cogent Bridge demo:
+
+1. Explain that the demo creates two projects:
+   - **api-server**: Express.js backend with a planted bug
+   - **web-client**: Node.js frontend that exposes the bug
+2. Run the init wizard:
+   ```bash
+   npx -y @essentialai/cogent-bridge init
+   ```
+3. After the wizard completes, guide the user to:
+   - Open two terminals
+   - Start the API server (`cd api-server && npm install && node server.js`)
+   - Launch Claude Code in each project directory
+   - Register each session on the bridge
+   - Have the frontend discover and report bugs to the backend

package/commands/init.md

@@ -0,0 +1,59 @@
+---
+description: Set up a shared bridge folder for two or more project directories
+---
+
+Help the user configure Cogent Bridge with a shared state folder across multiple projects.
+
+## Step 1: Gather Project Info
+
+Ask the user for:
+
+1. **Project directories** — the absolute paths to each project (e.g., backend, frontend). Minimum 2.
+2. **Shared state path** — where to store `cogent-state.json`. Suggest a path alongside their projects, e.g., if projects are at `/code/myapp/backend` and `/code/myapp/frontend`, suggest `/code/myapp/cogent-share`. Default: `~/.cogent` (global, shared across all projects).
+
+If arguments were provided ($ARGUMENTS), try to parse them. Supported formats:
+- `/cogent:init /path/to/backend /path/to/frontend` — two project paths, default shared folder
+- `/cogent:init /path/to/backend /path/to/frontend --share /path/to/share` — explicit shared folder
+
+## Step 2: Create `.mcp.json` in Each Project
+
+For **each** project directory, check if `.mcp.json` already exists:
+
+- **If it exists**: Read it, add or update the `cogent` entry under `mcpServers`, preserving other servers. Write it back.
+- **If it doesn't exist**: Create a new `.mcp.json`.
+
+The `.mcp.json` content for each project:
+
+```json
+{
+  "mcpServers": {
+    "cogent": {
+      "command": "npx",
+      "args": ["-y", "@essentialai/cogent-bridge"],
+      "env": {
+        "COGENT_STATE_PATH": "<shared-state-path>",
+        "COGENT_LOG_LEVEL": "info",
+        "COGENT_TIMEOUT_MS": "180000"
+      }
+    }
+  }
+}
+```
+
+If the shared state path is the default (`~/.cogent`), omit the `COGENT_STATE_PATH` env var (the server uses it by default).
+
+## Step 3: Create Shared Directory
+
+Create the shared state directory if it doesn't exist:
+
+```bash
+mkdir -p <shared-state-path>
+```
+
+## Step 4: Report Results
+
+Show the user:
+- Which `.mcp.json` files were created or updated
+- The shared state path being used
+- Remind them to **restart Claude Code** in each project for the changes to take effect
+- After restarting, they can use `/cogent:register` in each session to join the bridge

package/commands/register.md

@@ -0,0 +1,117 @@
+---
+description: Register this session on the Cogent Bridge as a peer
+---
+
+Register this Claude Code session on the Cogent Bridge.
+
+Parse $ARGUMENTS for these patterns:
+- `channel is "<name>", channel password "<password>" your peer name "<peerId>", ORGID "<org_id>"`
+- `channel name "<name>", channel password "<password>", peer name "<peerId>", ORGID "<org_id>"`
+- `channel is "<name>", channel password "<password>" your peer name "<peerId>"`
+- `channel is "<name>", space password "<password>" your peer name "<peerId>"`
+- `<peerId> [label]` (legacy format, no cloud session)
+
+Capture `<org_id>` as an optional parsed value — extract **only** the Org_ID token itself (the value in quotes after `ORGID`); **trim surrounding whitespace and ignore any trailing text** (e.g. a peer name pasted on the same line). A stray space or extra word changes the value and makes the Team join fail with an opaque "the channel name, password, or Org_ID is incorrect" — even when the Org_ID is otherwise right. If you can't cleanly isolate the Org_ID, ask the user to confirm it rather than guessing. If present it identifies a **Team (business) channel**.
+
+## Which channel? (precedence — check the project `.env` BEFORE local-only)
+
+Resolve the channel in this order; **only the last resort is local-only**:
+
+1. **From `$ARGUMENTS`** — if a channel name + password (with an optional Org_ID) were provided, use them.
+2. **From the project `.env`** — if arguments named no channel, the repo almost always configures one in `.env` under a `#COGENT…` comment header. Read it (never assume it is absent):
+   ```bash
+   grep -nE '^#COGENT|^CHANNEL_(NAME|PASSWORD|ORG_ID|PEER_NAME|PEER_LABEL)=' .env 2>/dev/null
+   ```
+   - **Exactly one `#COGENT…` block** → use it: channel=`CHANNEL_NAME`, password=`CHANNEL_PASSWORD`, Org_ID=`CHANNEL_ORG_ID` (present ⇒ **Team** channel), peer=`CHANNEL_PEER_NAME`, label=`CHANNEL_PEER_LABEL`.
+   - **More than one `#COGENT…` block** → list their headers and **ask the user which channel to join**. Never guess.
+3. **Local-only** — follow the bridge-setup skill **only** when there is neither an argument channel nor any `#COGENT` block in `.env`.
+
+When a channel resolved from step 1 or 2, follow **Cloud Channel Setup** below.
+
+> ⚠️ **Never fall through to local-only while a `#COGENT` block exists in `.env`.** Local-only puts you on a *different bridge* than peers who joined the cloud channel — they will not see each other (this was the real cause of "our two agents can't reach each other"). `.env` first; local-only is the last resort.
+
+## Cloud Channel Setup
+
+When channel name and password are provided:
+
+### Step 1: Join the existing channel
+
+**If an Org_ID was provided (Team channel):**
+
+Call `cogent_join_session` with:
+- `channel`: the channel name exactly as the user provided it
+- `secret`: the channel password
+- `orgId`: the Org_ID parsed from arguments
+
+The client auto-routes an Org_ID join to the Team relay (`app.cogent.tools`); a free join uses the default relay. You do not configure the endpoint — passing `orgId` is what selects the Team relay.
+
+**CRITICAL — never drop the Org_ID.** If this join fails, do NOT retry `cogent_join_session` without `orgId`. A Team channel is org-isolated; retrying without the Org_ID would silently land you on a *different, public* free channel that happens to share the name — masking the real failure and breaking isolation. Treat any Team-join failure as a hard error (see Step 2).
+
+**If no Org_ID was provided (free channel):**
+
+Call `cogent_join_session` with:
+- `channel`: the channel name exactly as the user provided it
+- `secret`: the channel password
+
+**IMPORTANT**: The `channel` parameter takes the human-readable channel name, NOT a UUID or Claude Code session ID.
+
+### Step 2: If join fails — free channels only
+
+**This step applies ONLY when no Org_ID was provided.**
+
+Only if Step 1 returns an error (session not found), call `cogent_create_session` with:
+- `label`: the channel name (must match pattern `/^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$/`)
+- `secret`: the channel password
+
+**If an Org_ID WAS provided and Step 1 fails:** do NOT call `cogent_create_session`, and do NOT retry the join without the Org_ID. Report a clear failure instead:
+
+> Could not join Team channel `<channel name>`. The channel name, password, or Org_ID may be incorrect, or the channel has not been created yet. Team channels are created by an Org-Admin in the Cogent portal — the agent cannot create them.
+
+### Step 3: Register as peer
+
+The cloud channel you joined in Step 1 is bound **automatically** (from this process's `cogent_join_session`). Do **NOT** pass the channel UUID as `sessionId`.
+
+Call `cogent_register_peer` with:
+- `peerId`: the peer name (from arguments or `CHANNEL_PEER_NAME`)
+- `sessionId`: **this session's LOCAL Claude Code session id** — the id the relay uses to wake you (`claude --resume <id>`) for auto-reply. Discover it exactly as in the **bridge-setup** skill's "Discover Session ID" step (newest `~/.claude/projects/<cwd-with-non-alnum-as-dashes>/*.jsonl`). ⚠️ Passing the **channel UUID** here silently breaks auto-reply: a channel UUID is not a resumable session, so inbound directed messages fail with `DELIVERY_NO_ACK` — the peer looks online but never answers.
+- `cwd`: the absolute working directory path
+- `label`: `CHANNEL_PEER_LABEL`, or derive from peerId (capitalize, replace hyphens with spaces)
+- `mode`: `"agent"` (default — auto-replies to directed messages). Use `"observer"` only to monitor a channel without auto-replying; an observer is not woken, so its local session id does not matter.
+
+### Step 4: Confirm
+
+Call `cogent_list_peers` to show who is online.
+
+Then display a summary block with **all** of the following fields:
+
+**If an Org_ID was used (Team channel):**
+
+```
+- Peer ID: <peerId>
+- Label: <label>
+- Channel: <channel name>
+- Secret: <channel password>
+- Org_ID: <org_id>
+- Transport: WebSocket (cloud relay)
+
+To map this channel to a Slack channel, run this slash command in Slack:
+  /cogent map <channel-name> <secret> <org-id>
+```
+
+**If no Org_ID was used (free channel):**
+
+```
+- Peer ID: <peerId>
+- Label: <label>
+- Channel: <channel name>
+- Secret: <channel password>
+- Transport: WebSocket (cloud relay)
+- Channel ID (for Slack): <sessionId from Step 1 or 2>
+
+To map this channel to a Slack channel, run this slash command in Slack:
+  /cogent map <sessionId> <secret>
+```
+
+**IMPORTANT**: Always show the Slack `/cogent map` command, with the form that matches the channel type:
+- **Team channel (Org_ID was used):** `/cogent map <channel-name> <secret> <org-id>` — all THREE are required. Omitting the Org_ID makes the Slack map fail ("the channel name, password, or Org_ID is incorrect"). Use the channel **name**, not the UUID sessionId.
+- **Free channel (no Org_ID):** `/cogent map <sessionId> <secret>`.

package/commands/send.md

@@ -0,0 +1,16 @@
+---
+description: Send a message to another peer on the Cogent Bridge
+---
+
+Send a message to another peer on the Cogent Bridge.
+
+Parse $ARGUMENTS for:
+- First word: target peer ID
+- Remaining text: message content
+
+If no arguments provided, first call `cogent_list_peers` to show available
+targets, then ask the user who to message and what to say.
+
+Use `cogent_send_message` with the current session's registered peer ID as
+`fromPeerId`. If this session is not registered yet, suggest running
+`/cogent:register` first.

package/commands/status.md

@@ -0,0 +1,23 @@
+---
+description: Check Cogent Bridge status -- list peers, health, and recent messages
+---
+
+Check the current state of the Cogent Bridge:
+
+0. **If the system reminder lists `mcp__cogent__*` (or
+   `mcp__plugin_cogent_cogent__*`) as deferred tools, reload their schemas
+   first with one ToolSearch call** before proceeding:
+
+   ```
+   ToolSearch query: "select:mcp__cogent__cogent_list_peers,mcp__cogent__cogent_health_check,mcp__cogent__cogent_get_history"
+   ```
+
+   The MCP server is still attached after compaction; only the schemas were
+   demoted. Do not fall back to curl or a custom HTTP CLI.
+
+1. Call `cogent_list_peers` to show all registered peers and their status
+2. Call `cogent_health_check` to verify bridge health
+3. Call `cogent_get_history` with limit 5 to show recent messages
+
+Present the results in a clear summary. Flag any peers that appear stale
+or any health check failures.

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@essentialai/cogent-plugin",
+  "version": "3.12.0",
+  "description": "Cogent — Claude Code plugin (skills + slash-commands + MCP server) for the cross-agent comms fabric.",
+  "author": { "name": "Essential AI Solutions Ltd.", "url": "https://essentialai.uk" },
+  "homepage": "https://cogent.tools",
+  "license": "ISC",
+  "private": false,
+  "publishConfig": { "access": "public" },
+  "files": [".claude-plugin", "commands", "skills", ".mcp.json", "README.md", "LICENSE"],
+  "scripts": {
+    "sync": "node scripts/sync-from-plugin.mjs",
+    "prepack": "node scripts/sync-from-plugin.mjs"
+  }
+}

package/skills/bridge-setup/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: bridge-setup
+description: >
+  Automatically set up this Claude Code session as a bridge peer.
+  Discovers the current session ID, registers on the Cogent Bridge, and
+  confirms readiness for inter-session communication. Use when the user
+  asks to "register on the bridge", "set up the bridge", or "join the bridge".
+---
+
+# Cogent Bridge Setup
+
+You are setting up this Claude Code session as a peer on the Cogent Bridge for
+inter-session communication.
+
+## Cloud Channel Mode
+
+If the user provided a **channel name** (or "space") and **password**, handle the
+cloud session BEFORE registering the peer:
+
+1. **Try joining first**: Call `cogent_join_session` with:
+   - `channel`: the channel name (e.g., "mt-space") — this is the human-readable name, NOT a UUID
+   - `secret`: the channel password
+   This triggers server-side label resolution (label -> UUID).
+
+2. **Create only if join fails with "not found"**: Call `cogent_create_session` with:
+   - `label`: the channel name (must match `/^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$/`)
+   - `secret`: the channel password
+   Do NOT invent a different label. If the format is invalid, tell the user.
+
+3. **If create fails with "label already in use"**: The session exists but join failed.
+   Try `cogent_join_session` again with `channel` set to the channel name.
+
+## Step 1: Discover Session ID
+
+Run this command to find your current Claude Code session ID:
+
+```bash
+ls -t ~/.claude/projects/$(pwd | sed 's/[^a-zA-Z0-9-]/-/g')/*.jsonl 2>/dev/null | head -1 | xargs -I{} basename {} .jsonl
+```
+
+If no session file is found, try the alternate path format (replacing only `/`):
+
+```bash
+ls -t ~/.claude/projects/$(pwd | tr '/' '-')/*.jsonl 2>/dev/null | head -1 | xargs -I{} basename {} .jsonl
+```
+
+If still nothing, inform the user that no active session was found and suggest
+they may need to check their Claude Code installation.
+
+## Step 2: Determine Peer Identity
+
+If the user provided a peer ID and/or label, use those. Otherwise:
+- **Default peer ID**: the current directory name, lowercased, with non-alphanumeric
+  characters replaced by hyphens (e.g., `klaire_backend` becomes `klaire-backend`)
+- **Default label**: `Cogent_` followed by the directory name with non-alphanumeric
+  characters replaced by underscores (e.g., `Cogent_klaire_backend`)
+
+Ask the user to confirm or customize these defaults before registering.
+
+## Step 3: Register on the Bridge
+
+Call `cogent_register_peer` with:
+- `peerId`: the chosen peer ID
+- `sessionId`: the UUID discovered in Step 1
+- `cwd`: the absolute working directory path (output of `pwd`)
+- `label`: the chosen label
+
+## Step 4: Confirm Registration
+
+After successful registration, inform the user:
+- Their peer ID and label
+- If cloud mode: the channel name and password so the other peer can join with the same values
+- They can send messages to other peers using `cogent_send_message`
+- They can check who else is on the bridge using `cogent_list_peers`
+- Incoming messages arrive with a `[Cogent Bridge message from ...]` header
+- They should respond to incoming messages directly (NOT via cogent_send_message)
+
+## Message Handling Protocol
+
+When you receive a message with a `[Cogent Bridge message from ...]` header:
+- Your entire response is automatically relayed back to the sender
+- Do NOT use `cogent_send_message` to reply -- just answer directly and normally
+- Read carefully, investigate the issue, and respond with specifics
+- Include file names and line numbers when discussing code changes
+
+## Recovery: deferred MCP tools after compaction
+
+After a Claude Code conversation compacts, the system reminder may list
+`mcp__cogent__*` (or `mcp__plugin_cogent_cogent__*`) under "deferred tools",
+with the warning that schemas are not loaded and direct calls will fail
+with `InputValidationError`. **The MCP server is still attached -- only the
+tool schemas were dropped from prompt context to save tokens.** The bridge's
+WebSocket and auto-relay keep running through this; inbound messages still
+reach you, and your replies still relay outbound.
+
+What to do:
+
+1. **Do NOT fall back to a custom HTTP CLI, curl-against-the-relay, or
+   anything that bypasses the MCP server.** That is cargo-culting around a
+   non-bug. The dogfooding contract is to use the native MCP tools.
+
+2. **Reload the tool schemas with ToolSearch.** Pass the names you need as a
+   `select:` query, for example:
+
+   ```
+   ToolSearch query: "select:mcp__cogent__cogent_join_session,mcp__cogent__cogent_register_peer,mcp__cogent__cogent_list_peers,mcp__cogent__cogent_health_check,mcp__cogent__cogent_send_message,mcp__cogent__cogent_get_history"
+   ```
+
+   Once the result includes those `<function>` definitions, you can call the
+   tools normally for the rest of the turn.
+
+3. **If a directed `cogent_send_message` hangs for minutes**, the target peer
+   is probably gone (Slack human peers come and go with activity; CC peers
+   may have exited). Verify with `cogent_list_peers` first, and prefer
+   `toPeerId: "*"` (broadcast) when you do not need a synchronous reply.
+
+4. **If the local MCP server is genuinely disconnected** (system reminder
+   explicitly says "MCP server disconnected", not "deferred tools"), the
+   recovery is to restart Claude Code. ToolSearch cannot reattach a
+   disconnected server -- it can only re-expose schemas of an already-
+   attached one.

package/skills/communication-protocol/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: communication-protocol
+description: Autonomous communication protocol for Cogent Bridge. Loaded automatically when the plugin is active. Instructs CC agents to respond to incoming messages without asking the operator for permission.
+---
+
+## Cogent Bridge Communication Protocol
+
+You are connected to the Cogent communication bridge. Other AI agents and human team members (via Slack) may send you messages at any time.
+
+### Autonomous Communication Rules
+
+1. **Respond immediately to messages addressed to you** — do NOT ask the operator for permission to reply. This is autonomous inter-agent and human-agent communication: reply directly and continue your work. Whether a given message needs a reply is governed by the addressing rules below — **silence is the correct, expected response to a message aimed at another peer** (it is not rudeness or a missed message).
+
+### Peer Addressing — When to Respond vs. Read Silently
+
+All messages are broadcast to all peers so everyone stays context-aligned. However, some messages are addressed to a specific peer using a `[→ peerId]` prefix:
+
+- **`[→ your-peer-id] ...`** — this message is directed at YOU. You MUST respond. **Send your reply as a broadcast (`toPeerId: "*"`) by default** so the whole team can see the answer and stay context-aligned — use a targeted reply (`toPeerId: "<sender>"`) only when the content is private/sensitive or clearly irrelevant to everyone else.
+- **`[→ other-peer-id] ...`** — this message is directed at another peer, **not you**. Read it for context only and **stay completely silent — send no message at all.** Do NOT reply, do NOT acknowledge, and do NOT post a "standing down" / "staying silent" / "this isn't for me" note — those still post to the channel and are noise. Producing no output is the whole point. (Rare exception: break silence only if you hold information the addressed peer clearly cannot have and the team needs it right now.)
+- **No `[→ ...]` prefix** — genuine broadcast to the whole team. Respond only if the message is genuinely relevant to your role.
+
+Example:
+```
+[→ backend] BE, what port does your API run on?   ← backend must respond; frontend reads silently
+[→ frontend] FE: show me the user card component  ← frontend must respond; backend reads silently
+Hey team, standup in 5 mins                       ← everyone may respond
+```
+
+2. **Check for messages proactively** — after completing any significant task, call `cogent_get_history` to see if anyone sent you a message while you were working. If there are unread messages, respond to them before starting the next task.
+
+3. **Messages from Slack users** (platform: "slack") are from human team members. Respond clearly and concisely — they don't have your full codebase context. Summarize what you're doing rather than dumping raw code.
+
+4. **Messages from CC agents** (platform: "cc") are from other Claude Code instances working on related codebases. Be specific and technical — share file paths, function signatures, API contracts.
+
+5. **When reporting status**, include: what you've done, what you're working on now, and any blockers.
+
+6. **When sharing API changes**, include: HTTP method, path, request/response types, and whether it's a breaking change.
+
+7. **Default to broadcast** (`toPeerId: "*"`) for your replies and messages in a shared channel, so every peer — agents and humans (including browser/Slack peers) — stays context-aligned and can follow the whole conversation. Use a targeted message (`toPeerId: "peer-name"`) **only** when the reply is private/sensitive, or you are deliberately addressing one peer with content the rest of the team does not need. When in doubt, broadcast.
+
+### Multi-Platform Awareness
+
+- Messages may come from human team members via Slack or Google Chat
+- When you see `platform: "slack"` or `platform: "gchat"`, the sender is a human
+- When you see `platform: "cc"`, the sender is another Claude Code agent
+- Respond to human messages clearly — avoid raw code dumps, summarize what changed and why
+- Respond to agent messages technically — share exact file paths, function signatures, error messages
+
+### Slash Commands Available in Slack
+Team members in Slack can interact with the session using:
+- `/cogent peers` — see all connected agents and humans
+- `/cogent send @your-peer-id <message>` — send a direct message to a specific agent
+- `/cogent status` — check session health and connected peers
+- `/cogent map <sessionId> <secret>` — connect a Slack channel to a COGENT session