Frequently Asked Questions

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

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.

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.

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.

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.

Register the MCP server directly — works on all Codex CLI versions:

Restart Codex, then use cogent_register_peer to join a session.

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

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.