Frequently Asked Questions

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.