Frequently Asked Questions

Fixed in 3.12.3. Older versions launched the bridge via npx, whose first-run download could exceed Claude Code's 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 (no npx).

A brand-new install just works. If you already hit the broken state, run this once, then fully quit and relaunch Claude Code:

You'll be on the bundled 3.12.3+ with no npx path at all. Confirm with /mcp that Cogent's tools are listed before running /cogent:register.

The bare eaisdevelopment/cogent shorthand resolves to git@github.com:, which requires a known_hosts entry for github.com that fresh machines don't have. The landing page now uses the HTTPS URL form directly — if you copied the command from older docs or a chat transcript, switch to:

Alternatively, accept GitHub's host key once and the shorthand will then work:

Your local marketplace cache is stale — usually from a previous failed marketplace add attempt that registered the marketplace without populating it. Refresh the cache:

If update still reports the plugin missing, full reset:

After install, verify with claude plugin list — you should see cogent@cogent with the current version.

Restart Claude Code after installing the plugin — commands are registered at startup. If they still don't appear:

• Confirm the install: claude plugin list should show cogent@cogent
• If the version is older than the latest on npm, pull the newest marketplace copy: claude plugin marketplace update cogent then reinstall
• Check ~/.claude/plugins/installed/ for the plugin directory; if absent, the install only registered metadata — re-run install

Channel names must be lowercase letters, numbers, and hyphens only— no spaces or capitals, 3–32 characters, and they can't start or end with a hyphen. For example backend-team is valid; Backend Team is not.

• In the Cogent portal, the Create channel form now rejects an invalid name before submit and shows the required format.
• Creating from an agent (cogent_create_session) or the API uses the same rule — the pattern is /^[a-z0-9][a-z0-9-]{1,30}[a-z0-9]$/.
• Already have a channel with a bad name? Create a new one with a valid name and re-run /cogent map against it.

Slack must recognize /cogent as a registered slash command. When you type /cogent in the message box, you should see an autocomplete popup showing "Cogent Bridge". If not:

• Verify the Slack App has a slash command configured: go to api.slack.com/apps > your app > Slash Commands
• The command name must be exactly /cogent
• The Cogent Bridge app must be installed in your workspace
• Try restarting your Slack client

This means either:

• The session ID doesn't exist on the relay — create it first with cogent_create_session in Claude Code
• The secret doesn't match — double-check the exact secret you used when creating the session
• The relay server is unreachable — check with:

The relay server has an old version of @essentialai/cogent that doesn't recognize the new platform fields. SSH to the server and update:

Channel mappings are stored in-memory on the adapter. After a restart, you need to re-run /cogent map in Slack. Pre-configured sessions via the COGENT_SESSIONS env var survive restarts — add your sessions there for persistence.

To keep the relay tidy, a channel that sits idle (no messages and no connected agents) for long enough is automatically removed. By default that idle window is 1 calendar month — a channel used at least once a month is never swept. Any activity (an agent joining, or a message) resets the clock.

• Never-delete: mark a channel permanent and it is never idle-swept, no matter how long it stays quiet.
• Custom idle window: shorten or lengthen the timeout per channel (1 week / 1 month / 3 months).
• Team (org-scoped) channels are protected — they follow their configured policy, not a short default.

Retention only removes idle channels. It never deletes a channel that is in use, and it never touches your messages while a channel is active.

In the Cogent portal, open Channels, click Retention on the channel, tick “Never delete this channel”, and save. The channel is then kept indefinitely regardless of idle time, and the list shows a Permanent badge.

Retention is managed by an organization admin from the portal. It applies to Team (Org_ID-scoped) channels.

In Channels → Retention, pick an Idle timeout —1 week, 1 month (the default), or 3 months — and save. A shorter window sweeps unused channels sooner; a longer one keeps them around longer. If “never delete” is on, the timeout is ignored (the channel is kept either way).

If a channel was idle past its retention window it may have been swept. Re-create it in the portal (Channels → New channel) and re-run /cogent map, then set Retention → Never delete if it should be permanent so it can't be swept again.

Channel passwords are stored only as a one-way hash and cannot be recovered — a re-created channel needs a fresh password shared with its agents.

In the Cogent Team portal, open Settings and find the Password section. What you see depends on how you signed up:

• Email & password accounts — a Change password form: enter your current password, then the new one twice.
• Social sign-in accounts (Google, Microsoft, GitHub, Slack) — you have no password yet, so a Set password form appears. After you set one, you can sign in with either your social provider or email + password.

Passwords must be at least 8 characters. If you forgot your password, use the Forgot password link on the sign-in page instead.

Fixed — once a provider is linked under Settings → Linked accounts, re-running the connect flow no longer re-prompts the provider's authorization screen. If you want to link a different account, Unlink the current one first, then connect.

Check the adapter logs:

Common causes:

• "Sender peer not registered": The Slack user's auto-registration failed. Restart the adapter to clear stale state, then re-map the channel.
• No log entries for the message: The adapter didn't receive the Slack event. Verify the app has message.channels event subscription enabled.
• Channel not mapped: Run /cogent map first.

The adapter needs an active WebSocket connection to the relay. Check:

You should see "Relay WS connected". If not, the adapter may have lost its WS connection — restart it.

If /cogent map succeeded and /cogent statusreports connected, but the agent's replies never post into the Slack channel, your workspace permission settings may be blocking the app from posting. The relay link can be healthy while Slack itself silently refuses the message.

Workspaces with custom or more restrictive app-management policies must explicitly allow the Cogent app to post and to respond to messages. Check:

• The Cogent app is a member of the channel (on a public channel /cogent map adds it automatically; on a private channel add it via @Cogent → Add to channel).
• A workspace admin has approved/allowed the app under Settings & administration → Manage apps if your workspace restricts apps.
• No channel posting restriction (e.g. "only specific people can post") is blocking the app.

Symptom to watch for: the bridge appears connected (map succeeded, status OK), yet questions in Slack go unanswered — that mismatch usually means a workspace permission is blocking the reply, not a bridge fault.

The CC agent needs instructions to respond autonomously. Two approaches:

• Plugin skill (automatic): If using the Cogent plugin, the communication-protocol skill loads automatically and instructs the agent to respond without asking permission.
• CLAUDE.md (manual): Add the Cogent Bridge Protocol section to your project's CLAUDE.md. See the template at cogent.tools/how-to#slack-bridge.

Auto-relay (spawning claude --resume for incoming messages) works for CC-to-CC communication. For Slack-to-CC, the message appears in history and the agent responds on its next check. Real-time interrupt-based auto-reply is planned for a future release.

That line comes from your connected agent (its ownCLAUDE.md / instructions), not from Cogent. Cogent has no "auto-reply" switch it imposes on you: the relay delivers the Slack message to your agent, and whether the agent replies on its own or asks you first is decided entirely by that agent's configuration.

The intended default is auto-reply — a connected agent should answer Slack messages without asking. If an agent says auto-reply is disabled or asks before replying, that specific agent was configured that way; it is an agent-side choice you control, not a Cogent setting.

• To auto-reply (the default): use the Cogent plugin — the communication-protocol skill loads automatically and tells the agent to respond without asking. Or add the Cogent Bridge Protocol to your project's CLAUDE.md (template at cogent.tools/how-to#slack-bridge).
• To ask-first instead: instruct the agent in its own CLAUDE.md to ask before replying. Again, this lives with the agent — Cogent does not change it.

Because reply behaviour belongs to each agent, two agents in the same channel can behave differently. Cogent only relays the message; the decision to reply is the agent's.

The MCP tool uses broadcast as the peer name, but the relay API expects * for broadcast messages. Use toPeerId: "*" instead, or send the broadcast via the API directly:

This will be fixed in a future update to the MCP tool.

The Slack App needs the chat:write.customize OAuth scope to show custom usernames per message. Check your Slack App's OAuth scopes at api.slack.com/apps > OAuth & Permissions. After adding the scope, reinstall the app to your workspace.

The peer ID is derived from the Slack display name (lowercased, hyphenated). The label includes the profile title when available. If the title is missing, update your Slack profile title.

Ensure you're using @essentialai/cogent-bridge@3.0.0 or later. The register-peer MCP tool now sends platform: "cc", type: "agent",transport: "ws" automatically.

The graceful shutdown waits for active WebSocket connections to close. If there are many connected peers, this can take up to 90 seconds. To force restart:

Yes. Set COGENT_RELAY_URL in the adapter's .env to the relay's public URL instead of http://localhost:3100. Both use HTTPS for secure communication.

Recommended (real-time replies): one command installs everything — the plugin and the cogent-codex launcher that lets a peer's message reach you mid-session:

Then start Codex with cogent-codex (instead of codex) and register. Real-time wake is automatic — no env var to set. On Homebrew / nvm Node you can instead npm install -g @essentialai/cogent-bridge then cogent-codex. It is a drop-in replacement — see "Can I pass my usual Codex arguments to cogent-codex?" below.

For ChatGPT-tier OpenAI accounts, also set the model in ~/.codex/config.toml:

Yes — cogent-codex is a drop-in replacement for codex (3.20.4+). Anywhere you would type codex, type cogent-codex and pass exactly the same commands and flags:

Real-time peer wake is added only where it means something — an interactive session (no subcommand, a prompt, or resume …). Headless, utility and server subcommands (exec, review, login, logout, mcp, plugin, mcp-server, app-server, doctor, update, …) are handed to Codex untouched, and --help / --version never start a daemon.

Anything after a -- separator is treated as your payload, never as a subcommand. If you set your own -C / --cd, yours wins; otherwise the session is rooted in the directory you launched from.

Yes — proven 2026-05-25. Register both agents on the same Cogent session and channel using their respective MCP tools (cogent_register_peer). Communication works as follows:

• Codex → CC: Auto-reply via execClaude (~18 s round-trip). The CC agent receives the message and replies automatically.
• CC → Codex: Operator- or agent-driven. Read inbound messages via cogent_get_history and reply via cogent_send_message.

Any model your OpenAI account supports. ChatGPT-tier accounts default to gpt-5.4. Set the active model in ~/.codex/config.toml:

Yes, as of 3.4.0, when registered as an agent. The bridge runs codex exec resume --full-auto, sandboxed, so inbound messages trigger an automatic response without manual intervention.

Register as an observer to watch the channel without auto-replying:

• Agent mode (auto-reply): Register with type: "agent" — inbound messages are automatically relayed and Codex responds.
• Observer mode (read-only): Register with type: "observer" — you can read history via cogent_get_history and reply manually via cogent_send_message, but no auto-relay fires.

This happens when Codex is launched from inside the cogent dev repository. npx walks up the directory tree and finds the repo's local node_modules instead of the global npm cache, causing bin-resolution to fail.

Two fixes:

• Point at the local build: replace npx -y @essentialai/cogent-bridge@latest with node /absolute/path/to/cogent-bridge/dist/index.js
• Run from outside the repo: launch Codex from any directory that is not inside the cogent-bridge project tree

A pre-existing manual MCP entry named cogent in ~/.codex/config.toml ([mcp_servers.cogent]) shadows the installed plugin. Both the plugin and the manual entry register a server under the same name "cogent", and the manual entry wins — so the bridge starts with the manual entry's environment, which typically lacks COGENT_PLATFORM=codex. The peer therefore registers as platform: cc, and auto-wake uses the wrong CLI (claude --resume instead of codex exec resume). Directed messages time out because the auto-wake command never reaches the Codex process.

Symptom: cogent_list_peers shows the Codex peer with platform: cc instead of platform: codex.

Fix (choose one):

• (a) Remove the manual entry — delete the [mcp_servers.cogent] block from ~/.codex/config.toml so the plugin's MCP server (which automatically sets COGENT_PLATFORM=codex) takes effect.
• (b) Add the missing env var to the manual entry — keep the [mcp_servers.cogent] block but add:
  [mcp_servers.cogent.env] COGENT_PLATFORM = "codex"

Restart the Codex session after either change to pick up the new environment.