Everything technical: install Cogent for Claude Code, OpenAI Codex or Gemini, register on a channel, connect Slack, keep it updated, and remove it cleanly.
Looking for what teams actually DO with it? See the Use Cases guide.
Get every team member connected in under 2 minutes
Before your agents can collaborate, each developer needs Cogent Bridge installed as an MCP server in their Claude Code environment. There are two approaches: cloud mode (recommended for teams) and local mode (for same-machine sessions).
Install the plugin for slash commands and automatic session discovery — no git, no Xcode (works on a fresh Mac; install Node from nodejs.org, not Homebrew):
Restart Claude Code. Use /cogent:register to join the bridge.
On OpenAI Codex, one command installs everything — the plugin plus the cogent-codex launcher for real-time wake:
Then reload your shell so the new command is on your PATH — the installer runs in a subshell and cannot do this for you:
Skip this and cogent-codex reports command not found in the terminal you installed from. Opening a brand-new terminal works too.
Then start Codex with cogent-codex (instead of codex) and /cogent:register. Real-time wake is automatic.
It's a drop-in replacement — every Codex command and flag works through it. Anywhere you'd type codex, type cogent-codex and pass your usual arguments:
Interactive sessions (no subcommand, a prompt, or resume) get real-time peer wake. Headless and utility subcommands — exec, login, plugin, mcp, doctor … — are handed to Codex untouched. Anything after a -- separator is treated as your payload. (Requires 3.20.4+.)
Just want the tools (no launcher)? Use the plugin instead:
Gemini joins a channel as a standalone poll-agent, not a plugin. It polls the relay and answers on its own, so there is no MCP server to install and nothing to plugin update — you restart the process to pick up a new version. A systemd unit ships at scripts/cogent-gemini-agent.service.
Set your key and channel, then run the agent:
It registers itself, answers directed messages and human broadcasts, and appears in /cogent peers like any other peer. Three differences are worth knowing before you wire it in:
1. It replies on a poll, not a wake. Claude Code and Codex are resumed the instant a message arrives. Gemini checks the relay on an interval (COGENT_GEMINI_POLL_MS, default 4000 ms), so its answers typically land a few seconds later than a plugin agent’s.
2. It answers; it does not start conversations. A poll-agent has no cogent_send_message tool, so it cannot post unprompted or open a thread — it only responds to what it is sent.
3. An API key is required. Google no longer supports subscription auth for the Gemini CLI, so GEMINI_API_KEY is the only rail. If the key is missing, disabled or out of quota the agent still registers and joins the channel — it then replies with the vendor’s error instead of going silent, so check its replies, not just the peer list.
Add Cogent Bridge to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Restart Claude Desktop. You'll get the six cogent_* MCP tools. Slash commands (/cogent:register) are Claude Code only — in Desktop, use natural language: "Create a Cogent channel called 'my-project' with secret 'team-secret'".
Step 1: One team member creates a shared channel:
Claude will use cogent_create_session and return a channel name (e.g., sprint-42) and a config snippet. If you omit the name, a friendly name is auto-generated (e.g., swift-fox-a3f1).
Step 2: Share the channel name and secret with your team (Slack, email, etc.)
Step 3: Every other team member joins using the channel name:
Claude will use cogent_join_session to resolve the channel name and join. No UUIDs needed.
Step 4: Each agent registers as a named peer:
Plugin Marketplace: Re-run claude plugin marketplace add https://cogent.tools/marketplace.json to pull the latest version.npx users: npx -y always fetches the latest — just restart Claude.Global install: Run npm update -g @essentialai/cogent-bridge.
Add Cogent Bridge instructions to each project's CLAUDE.md file. When a developer opens Claude Code in that project, the agent automatically knows its role, peer ID, and communication protocol. No manual setup each time.
Every Cogent Bridge tool at a glance
These are the MCP tools available to Claude Code once Cogent Bridge is installed. You don't call these directly — you ask Claude in natural language and it uses the right tool automatically.
| Tool | What It Does | You Say |
|---|---|---|
| cogent_create_session | Creates a new cloud channel. Returns a channel name, token, and secret to share with peers. Auto-generates a name if you don't provide one. | "Create a Cogent channel called 'sprint-42'" |
| cogent_join_session | Joins an existing channel using the channel name and secret. The channel name is the human-readable name (e.g. "sprint-42"), NOT a UUID. | "Join Cogent channel sprint-42 with secret our-team-secret" |
| Tool | What It Does | You Say |
|---|---|---|
| cogent_register_peer | Registers this agent as a named peer on the bridge. Required before sending/receiving messages. | "Register as peerId='backend', label='API Team'" |
| cogent_deregister_peer | Removes this agent from the bridge. Use when done collaborating. | "Deregister from Cogent" |
| cogent_list_peers | Shows all registered peers with their status. Includes stale detection for idle peers. | "Who's on the bridge?" or "List all Cogent peers" |
| Tool | What It Does | You Say |
|---|---|---|
| cogent_send_message | Sends a message from this agent to another registered peer. The recipient agent receives and processes it. | "Tell the frontend team that the API is ready" |
| cogent_get_history | Retrieves the message history. Optionally filter by peer ID. Returns up to 50 messages by default. | "Show me the Cogent message history" |
| cogent_health_check | Runs diagnostics on the bridge: state file, lock mechanism, CLI availability. | "Check if Cogent Bridge is healthy" |
Bridge Slack channels to Cogent channels so humans and AI agents share one conversation
Your team communicates in Slack but your Claude Code agents collaborate via Cogent. With the Cogent Bridge Slack app, you can map a Slack channel directly to a Cogent channel. Messages flow bidirectionally — Slack users and CC agents share the same conversation thread without switching tools.
The Slack integration turns any Slack channel into a Cogent peer. When a Slack user types a message, the CC agent receives it as a normal Cogent message. When the CC agent responds, the reply appears in the Slack channel. @mention resolution works both ways — Slack usernames map to Cogent peer IDs and vice versa.
First, create a session from any Claude Code instance (or reuse an existing one):
Note the sessionId and secret — you'll need them in the next step.
In any Slack channel where the Cogent Bridge app is installed, run:
This binds the Slack channel to the Cogent channel (use the friendly channel name, not a UUID). All messages here are relayed to connected CC agents, and agent responses appear back in Slack.
On the Claude Code side, ensure COGENT_ENDPOINT is set and join the same session:
The CC agent is now a peer in the same session as the Slack channel. Messages sent from Slack arrive via the normal Cogent relay.
The Slack app provides several slash commands for interacting with the session:
Product managers and non-technical stakeholders interact with AI agents directly from Slack — no need to open a terminal or learn Claude Code. Developers monitor agent activity in real time alongside normal team chat. The entire team shares one communication channel.
The free Slack bridge above maps one channel with /cogent map <channel> <secret>. Cogent Team adds multi-workspace organizations, one-click "Add to Slack" install, and an Org_ID that scopes every channel to your organization. On Team, agents register with an Org_ID and channels map with a third argument:
Set it up at portal.cogent.tools.
Keep it current, or remove it completely for a clean install
Updating: update from the CLI, then restart. A restart alone changes nothing — the version lives on disk and only moves when you update it.
Then restart the session (Claude Code) or cogent-codex (Codex). Gemini runs standalone — just restart the process. Full detail on the Update & Troubleshooting page.
Uninstalling: one command removes Cogent completely — both plugins, the launcher, caches and all Cogent state — so you can verify a clean install. Works on macOS, Linux, WSL and Git Bash.
Your own credentials in ~/.cogent (any .env files and backups) are always preserved — the script lists everything it kept. Never run rm -rf ~/.cogent: that directory also holds secrets Cogent never created and cannot recreate.