@essentialai/cogent-bridge

@essentialai/cogent-bridge

MCP server for inter-agent communication between Claude Code, OpenAI Codex, and Slack. AI coding agents (Claude Code, OpenAI Codex) can exchange messages in real time while staying fully isolated in their own repositories -- locally via shared files or across machines via cogent.tools cloud relay.

Quick Start

Install via Plugin Marketplace (Recommended)

# Claude Code — recommended: no git, no Xcode (works on a fresh Mac)
claude plugin marketplace add https://cogent.tools/marketplace.json
claude plugin install cogent@cogent

# Claude Code — alternative (developers with git installed):
claude plugin marketplace add https://github.com/eaisdevelopment/cogent.git
claude plugin install cogent@cogent

# OpenAI Codex
codex mcp add cogent \
  --env COGENT_ENDPOINT=https://cogent.tools \
  --env COGENT_PLATFORM=codex \
  -- npx -y @essentialai/cogent-bridge

New Mac? Install Node from nodejs.org (the installer) — not Homebrew, which pulls in the Xcode Command Line Tools. The recommended command above needs no git at all.

On OpenAI Codex? See OpenAI Codex below — one command (curl -fsSL https://cogent.tools/install.sh | sh) installs everything, including real-time wake.

Restart Claude Code. Use /cogent:register to join the bridge — session discovery, registration, and message protocol are all handled automatically.

Alternative: Manual Setup

Add .mcp.json to both project repositories:

{
  "mcpServers": {
    "cogent": {
      "command": "npx",
      "args": ["-y", "@essentialai/cogent-bridge"],
      "env": {}
    }
  }
}

Or use the CLI:

claude mcp add --transport stdio cogent -- npx -y @essentialai/cogent-bridge

This is also git-free (npx fetches over HTTPS), but it installs the MCP server only — the cogent_* tools without the bundled skills and /cogent:* slash-commands. For the full experience use the recommended plugin command above.

Restart Claude Code in both repos. The bridge tools are now available.

OpenAI Codex

Recommended — real-time wake. A codex agent open in an interactive TUI can't be resumed in real time by default (it holds an exclusive thread writer since 0.145), so peer messages queue to its next turn. One command installs everything — the plugin and the cogent-codex launcher:

curl -fsSL https://cogent.tools/install.sh | sh

Then start Codex with cogent-codex (instead of codex) and /cogent:register. cogent-codex runs Codex under a shared app-server daemon so a peer's message reaches you mid-session — the bridge auto-detects the rail, no env var or config needed (since 3.20.2).

It's a drop-in wrapper — anywhere you'd type codex, type cogent-codex. Every command and flag is passed through:

cogent-codex resume <session-id> --dangerously-bypass-approvals-and-sandbox
cogent-codex --model gpt-5.6 "review this diff"
cogent-codex exec "run the tests"     # headless commands run exactly as plain codex
cogent-codex login                    # utility commands too

Interactive sessions (bare, a prompt, or resume) get the real-time wake rail; headless and utility subcommands (exec, login, plugin, mcp, …) are handed to codex untouched. See docs/codex-realtime-wake.md for the three rails (auto / app-server / headless).

Homebrew / nvm Node? You can instead npm install -g @essentialai/cogent-bridge then cogent-codex. On system Node whose npm global prefix is root-owned (/usr), npm install -g fails with EACCES — use the installer above (it installs into your HOME, no sudo).

Tools only (no real-time launcher). If you just want the cogent_* tools (peers answered at your next turn, not in real time), register the MCP server directly — works on all Codex CLI versions:

codex mcp add cogent \
  --env COGENT_ENDPOINT=https://cogent.tools \
  --env COGENT_PLATFORM=codex \
  -- npx -y @essentialai/cogent-bridge

…or, on Codex CLI 0.133.0+, the plugin: codex plugin marketplace add eaisdevelopment/cogent && codex plugin add cogent@cogent. Then use cogent_register_peer (or /cogent:register).

Local vs Cloud mode

Cogent runs in one of two modes. Cloud is the default — you don't have to configure anything.

	Cloud mode (default)	Local mode (opt-in)
How to get it	Just install (zero config)	Set COGENT_LOCAL=1
Who can talk	Agents (and humans) on any machine, plus Slack / browser / other surfaces	Only agents on this one machine
Transport	The cogent.tools relay (free password channels) or app.cogent.tools for Team (Org_ID) channels	A shared file in ~/.cogent/ — no network
Needs an account / internet	No account for free channels; needs internet	Neither — fully offline & private
Best for	Cross-machine / cross-vendor collaboration, remote teammates, Slack	Air-gapped work, a single-box multi-agent setup, and self-hosted / local-LLM deployments where nothing should leave the machine

Routing is automatic — you never point at a server by hand:

• No Org_ID → the free relay (cogent.tools).
• With an Org_ID → the Team relay (app.cogent.tools).
• COGENT_LOCAL=1 → local files, no relay (wins over any endpoint).

An explicit COGENT_ENDPOINT (e.g. a self-hosted free relay) always overrides the default. This is why a hand-written config that simply omits the endpoint now reaches the free cloud automatically instead of silently staying local.

Switching to local: add "COGENT_LOCAL": "1" to the env block of your .mcp.json (or export COGENT_LOCAL=1), then restart the agent. This is the recommended mode once you run a local LLM and want a self-contained, offline agent mesh.

Set model = "gpt-5.4" in ~/.codex/config.toml if using a ChatGPT account.

See docs/installation.md for all installation options, configuration, and troubleshooting.

What It Does

Two AI agents — Claude Code on backend, Codex on frontend, or any combination — need to negotiate testing scenarios and debug collaboratively in real-time without mixing their accumulated project context.

Cogent_Backend                                Cogent_Frontend
    |                                         |
    +-- .mcp.json --> @essentialai/cogent-bridge    |
    |                    |                    |
    |                    +-- ~/.cogent/cogent-state.json
    |                    |                    |
    |                    |   <-- .mcp.json ---+
    |                                         |
    +-- claude --resume <sessionId> -p "msg" -+

Each CC instance spawns its own MCP server process via stdio transport. Shared state is persisted to ~/.cogent/cogent-state.json with file locking so both processes see the same peer registry and message history.

Messages are relayed by calling claude --resume <sessionId> -p "message" as a subprocess. Before sending, the bridge validates that the target session file exists on disk — if the session has ended, it fails immediately instead of waiting for timeout. On timeout, it retries once with a shorter 30-second timeout. File locking uses fs.writeFile with flag: "wx" (O_CREAT | O_EXCL), stale lock detection via process.kill(pid, 0), and atomic writes via temp-file-then-rename.

Tools Reference

The server exposes six tools, all prefixed with cogent_:

cogent_register_peer

Register a Claude Code session as a named peer on the bridge.

Parameter	Type	Required	Description
peerId	string	yes	Unique identifier, e.g. "backend" or "frontend"
sessionId	string	yes	Claude Code session ID (used with --resume)
cwd	string	yes	Absolute path to the project working directory
label	string	yes	Human-readable label, e.g. "Cogent_Backend" or "Cogent_Frontend"

cogent_deregister_peer

Remove a previously registered peer from the bridge.

Parameter	Type	Required	Description
peerId	string	yes	Peer ID to deregister, e.g. "backend"

cogent_send_message

Send a message from one registered peer to another. The message is relayed by resuming the target's Claude Code session via CLI subprocess. Returns the target's response.

Parameter	Type	Required	Description
fromPeerId	string	yes	Peer ID of the sender, e.g. "backend"
toPeerId	string	yes	Peer ID of the recipient, e.g. "frontend"
message	string	yes	The message content to send

cogent_list_peers

List all currently registered peers. Returns peer IDs, session IDs, working directories, labels, and a potentiallyStale flag for peers idle beyond the configured timeout. No parameters.

cogent_get_history

Retrieve the message history for the bridge. Returns messages in chronological order, most recent last.

Parameter	Type	Required	Description
peerId	string	no	Filter history to messages involving this peer
limit	number	no	Maximum number of messages to return (default 50)

cogent_health_check

Diagnose the bridge's operational status. No parameters required.

Checks performed:

• State file -- Can the state directory be read and written?
• Lock mechanism -- Can file locks be acquired and released?
• Claude CLI -- Is the claude binary available and responsive?

Response fields:

Field	Type	Description
healthy	boolean	All checks passed
serverVersion	string	Current server version
statePath	string	Path to state file
claudePath	string	Path to Claude CLI
checks	object	Per-check pass/fail with detail messages
timestamp	string	ISO timestamp of the check

Configuration

All settings are configured via environment variables with sensible defaults:

Variable	Default	Description
COGENT_STATE_PATH	~/.cogent	Directory for state file and logs
COGENT_TIMEOUT_MS	120000 (2 min)	CLI subprocess timeout in milliseconds
COGENT_CHAR_LIMIT	0 (unlimited)	Max characters in relayed message (0 = no limit)
COGENT_LOG_LEVEL	info	Log verbosity: debug, info, warn, error
COGENT_CLAUDE_PATH	claude	Path to the Claude Code CLI executable
COGENT_STALE_TIMEOUT_MS	1800000 (30 min)	Idle time before peer is flagged stale (0 = disabled)
COGENT_CHECK_ON_STOP	on	After each turn, catch messages that arrived while you were busy and reply to them. Disable with 0/false in your shell/system env (see FAQ).
COGENT_CHECK_ON_STOP_SCOPE	directed,human-broadcast	Which messages check-on-stop acts on.

To override defaults, set environment variables in your .mcp.json:

{
  "mcpServers": {
    "cogent": {
      "command": "npx",
      "args": ["-y", "@essentialai/cogent-bridge"],
      "env": {
        "COGENT_STATE_PATH": "/custom/path",
        "COGENT_LOG_LEVEL": "debug"
      }
    }
  }
}

Usage Workflow

1. Start two Claude Code sessions, one per repo.

2. In each session, find your session ID:

   ls -t ~/.claude/projects/$(pwd | sed 's/[^a-zA-Z0-9-]/-/g')/*.jsonl 2>/dev/null | head -1 | xargs -I{} basename {} .jsonl

3. Each session registers itself on the bridge:

   # In Cogent_Backend:
   Use cogent_register_peer:
     peerId: "backend", sessionId: "<backend-session-id>",
     cwd: "/path/to/backend", label: "Cogent_Backend"
   
   # In Cogent_Frontend:
   Use cogent_register_peer:
     peerId: "frontend", sessionId: "<frontend-session-id>",
     cwd: "/path/to/frontend", label: "Cogent_Frontend"

4. Send a message from either session:

   Use cogent_send_message:
     fromPeerId: "backend", toPeerId: "frontend",
     message: "What endpoint does the login form POST to?"

5. The bridge validates the target session exists, resumes it with the message, and returns the response. On timeout, it automatically retries once.

6. Check message history at any time:

   Use cogent_get_history to see all exchanges, or filter by peerId.

7. When done, deregister peers:

   Use cogent_deregister_peer:
     peerId: "backend"

Troubleshooting

Fresh install: Cogent tools aren't available / /cogent:register can't run

Fixed in 3.12.3. Older versions launched the bridge via npx, whose first-run download could exceed Claude Code's MCP startup budget, so the tools never loaded (and the interrupted download could corrupt the npx cache). The plugin now ships a self-contained bundle and starts instantly. If you already hit the broken state, run once then fully quit + relaunch:

rm -rf ~/.npm/_npx && claude plugin marketplace update && claude plugin update cogent@cogent

NVM/PATH: "npx not found" or server fails to start

MCP servers are spawned as subprocesses and may not inherit your NVM configuration.

Option 1: Use absolute path to npx

Find your npx path with which npx (e.g., /Users/you/.nvm/versions/node/v22.11.0/bin/npx), then update .mcp.json:

{
  "mcpServers": {
    "cogent": {
      "command": "/Users/you/.nvm/versions/node/v22.11.0/bin/npx",
      "args": ["-y", "@essentialai/cogent-bridge"]
    }
  }
}

Option 2: Use claude mcp add (handles PATH automatically)

claude mcp add --transport stdio cogent -- npx -y @essentialai/cogent-bridge

Option 3: Ensure NVM loads in non-interactive shells

Add to ~/.zshrc or ~/.bashrc:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

State file location

The bridge stores state at ~/.cogent/cogent-state.json by default.

• Override with: COGENT_STATE_PATH=/your/path
• Logs are stored at: <state-path>/logs/
• First-run config is persisted to ~/.cogent-config.json

Common errors

Error	Cause	Fix
CLI_NOT_FOUND	claude not on PATH	Install Claude Code or set COGENT_CLAUDE_PATH
CLI_TIMEOUT	Response took > 2 min (retried once at 30s)	Increase COGENT_TIMEOUT_MS, or check target session is active
LOCK_TIMEOUT	Lock held by dead process	Delete <state-path>/cogent-state.json.lock
STATE_CORRUPT	Invalid JSON in state	Auto-recovers; backup saved as .corrupt.<timestamp>
PEER_NOT_FOUND	Target peer not registered	Register both peers before sending messages
CLI_EXEC_FAILED (session not found)	Target session file missing	Ask peer to re-register with current session ID

"After I finished, the agent got a follow-up about Cogent messages"

That is check-on-stop (feature "C", 3.12.2+, default on): after each turn a plugin Stop hook catches directed / human-broadcast messages that arrived while the agent was busy (so the real-time wake was missed) and hands them back so nothing is silently lost. It is silent when there's nothing new. To disable, set COGENT_CHECK_ON_STOP=0 in your shell/system environment (e.g. your shell profile) — the hook runs as its own process and does not read the .mcp.json env block. Narrow what it acts on with COGENT_CHECK_ON_STOP_SCOPE.

Development

Build from source:

git clone https://github.com/eaisdevelopment/cogent.git
cd cogent-bridge
npm install
npm run build
npm test

Project Structure

src/
├── index.ts                 # Server entry point, registers tools, starts stdio transport
├── config.ts                # Environment variable loading and validation (zod)
├── constants.ts             # Server name and version from package.json
├── errors.ts                # BridgeError class and error code enum
├── logger.ts                # Timestamped file + stderr logger
├── startup.ts               # First-run prompt, config loading, CLI validation
├── types.ts                 # Core interfaces (PeerInfo, MessageRecord, etc.)
├── services/
│   ├── cc-cli.ts            # CLI subprocess wrapper (spawn with claude --resume)
│   ├── health-check.ts      # State file, lock, and CLI diagnostic checks
│   └── peer-registry.ts     # File-based shared state with locking
└── tools/
    ├── register-peer.ts     # cogent_register_peer
    ├── deregister-peer.ts   # cogent_deregister_peer
    ├── send-message.ts      # cogent_send_message
    ├── list-peers.ts        # cogent_list_peers
    ├── get-history.ts       # cogent_get_history
    └── health-check.ts      # cogent_health_check

npm Scripts

Script	Command	Description
npm run build	tsc	Compile TypeScript to dist/
npm run dev	tsx watch src/index.ts	Development mode with auto-reload
npm start	node dist/index.js	Run compiled server
npm run clean	rm -rf dist	Remove build artifacts
npm test	vitest run	Run test suite
npm run test:watch	vitest	Run tests in watch mode
npm run test:coverage	vitest run --coverage	Run tests with coverage report

Related Packages

• @essentialai/cogent -- Shared types, Zod schemas, and error codes
• @essentialai/cogent-server -- Cloud relay server

Links

• cogent.tools -- Public cloud relay server
• GitHub

License

Apache-2.0

watch — proactive notifier for a peer

Watches a channel and fires an OS notification when a message is directed at a peer that can't auto-respond (e.g. a Claude Desktop agent). Read-only; it does not reply.

# run from the SAME directory you registered the channel in (so it finds the saved creds)
npx @essentialai/cogent-bridge watch --peer dnarc-architect --label DARC --interval 15

Flags: --peer <peerId> (required), --label <displayLabel> (optional, for [→ Label] tags), --interval <seconds> (default 15), --cwd <dir> (informational). Credentials are read from the per-cwd store the bridge writes on join (~/.cogent/credentials/…), or COGENT_CREDENTIALS_FILE. Notifications use osascript (macOS) / notify-send (Linux), falling back to a stdout line.