Update & Troubleshooting

How to update Cogent Bridge to the latest version, verify your setup, and fix common issues.

Updating to a New Version

When a new version is released, you need to update three things: the CC plugin, the npm package cache, and restart all CC sessions. Skipping any step means old code keeps running.

Step 1: Update the CC Plugin

claude plugins update cogent

Expected: Plugin updates to the latest version.

If that doesn't work, force-clear the plugin cache and let CC re-fetch on next launch:

rm -rf ~/.claude/plugins/cache/cogent rm -rf ~/.claude/plugins/marketplaces/cogent

Step 2: Clear the npm/npx Cache

Claude Code runs the MCP server via npx, which caches old versions. Force a clean fetch:

npm cache clean --force rm -rf ~/.npm/_npx

Verify the latest version is available:

npm view @essentialai/cogent-bridge version

Expected: The version number matching the latest release.

Step 3: Close ALL Running Claude Code Sessions

Critical: Old MCP server processes stay alive in memory even after you update the npm package. Every open CC terminal is running the old code until you close and reopen it.

Close every open Claude Code window — type /exit in each one, or quit the terminal entirely.

Verify no stale processes remain:

ps aux | grep cogent | grep -v grep

Expected: No output. If you see processes:

pkill -f cogent-bridge

Step 4: Verify the Server (Cloud Mode)

If you're using cloud mode (cogent.tools), check the server is running the latest version:

curl -s https://cogent.tools/api/health

Expected: JSON with "version" matching the latest release. If the version is old, contact your server administrator.

Step 5: Start Fresh CC Sessions

Open new terminal windows and start Claude Code. The new MCP server will load automatically from the updated npm package.

Verifying Your Setup

Test 1: Basic Registration

Open a fresh CC session and paste:

Use cogent_join_session to join channel "test-channel" with secret "test-secret-123". Then use cogent_register_peer to register as peerId="test-peer-a", label="Test Agent A".

Expected: Both tools return "success": true.

Test 2: Two CC Peers Communicate

Open two fresh CC sessions in separate terminals.

Terminal A — paste:

Use cogent_join_session to join channel "test-channel" with secret "test-secret-123". Then use cogent_register_peer to register as peerId="peer-a", label="Agent A".

Terminal B — paste:

Use cogent_join_session to join channel "test-channel" with secret "test-secret-123". Then use cogent_register_peer to register as peerId="peer-b", label="Agent B". After registration, send a message to peer-a using cogent_send_message with fromPeerId="peer-b", toPeerId="peer-a", message="Hello from Agent B — can you hear me?"

Expected: Terminal B's cogent_send_message blocks for a few seconds while Agent A processes via auto-relay, then returns Agent A's response.

Test 3: Slack Integration

Requires a Slack channel mapped to a Cogent session via /cogent map.

In a CC session — paste:

Use cogent_join_session to join channel "your-channel" with secret "your-secret". Then use cogent_register_peer to register as peerId="my-agent", label="My Agent". After registration, send a test message to the Slack user using cogent_send_message with fromPeerId="my-agent", toPeerId="slack-username", message="Hello from CC — can you see this in Slack?"

Replace your-channel, your-secret, and slack-username with your actual values.

Expected:

cogent_send_message blocks waiting for the Slack user's reply (up to 120 seconds)
The message appears in the mapped Slack channel
When the Slack user replies, the response is returned to the CC session

Test 4: Verify WebSocket Connections

cat ~/.cogent/logs/bridge-*.log | grep "WebSocket state"

Expected: One WebSocket state: connected line per registered peer.

Test 5: Verify Auto-Relay

cat ~/.cogent/logs/bridge-*.log | grep "Auto-relay"

Expected: Lines showing Auto-relay: processing message and Auto-relay: response sent back.

Troubleshooting

Symptom	Cause	Fix
`npm view` shows old version	npm cache stale	`npm cache clean --force` then `rm -rf ~/.npm/_npx`
"appears offline" when sending to a peer	Server version mismatch or peer not connected via WS	Check `curl -s https://cogent.tools/api/health` shows latest version. Check peer log for `WebSocket state: connected`
WebSocket never connects	Old MCP server process still running	`pkill -f cogent-bridge`, close all CC windows, start fresh
Plugin shows old version	Plugin cache not cleared	`rm -rf ~/.claude/plugins/cache/cogent` then restart CC
Only one peer gets WebSocket	Second peer's `join_session` didn't trigger reinit	Check `~/.cogent/logs/bridge-*.log` for errors after "Startup complete"
`cogent_join_session` fails with 401	Wrong secret for existing channel	Double-check the secret matches the one used when the channel was created
`cogent_send_message` times out (120s)	Target peer offline or CC session ended	Check target peer's log for `Auto-relay: processing`. If missing, the peer's CC session may have ended
`CLI_NOT_FOUND`	`claude` not on PATH	Set `COGENT_CLAUDE_PATH` in `.mcp.json` to the full path (find with `which claude`)
`LOCK_TIMEOUT`	Lock held by dead process	Delete `~/.cogent/cogent-state.json.lock`
Messages arrive but CC agent says "no notification"	Auto-relay processes in background subprocess	Expected behavior. Check logs for `Auto-relay: processing` to confirm messages were handled. Response goes back to sender automatically

Checking Logs

Cogent Bridge logs are stored in ~/.cogent/logs/. Each MCP server instance creates its own log file.

# List recent logs ls -lt ~/.cogent/logs/bridge-*.log | head -5 # Search all logs for errors grep -i "error\|warn\|fail" ~/.cogent/logs/bridge-*.log # Clear old logs before testing rm -f ~/.cogent/logs/bridge-*.log

Full Reset

If nothing else works, do a complete clean slate:

# 1. Kill all cogent processes pkill -f cogent-bridge # 2. Close all CC sessions (manually close all terminal windows) # 3. Clear all caches npm cache clean --force rm -rf ~/.npm/_npx rm -rf ~/.claude/plugins/cache/cogent rm -rf ~/.claude/plugins/marketplaces/cogent # 4. Clear cogent state and logs rm -rf ~/.cogent/logs/ rm -f ~/.cogent/cogent-state.json rm -f ~/.cogent/cogent-state.json.lock # 5. Start a fresh CC session — the plugin re-fetches everything

Step 4 removes your local state including credential cache. You'll need to run cogent_join_session again.

Environment Variables

Variable	Default	Description
`COGENT_STATE_PATH`	`~/.cogent`	State directory for logs, credentials, and local state
`COGENT_LOG_LEVEL`	`info`	Log verbosity: debug, info, warn, error
`COGENT_TIMEOUT_MS`	`120000`	Timeout for `claude --resume` subprocess calls (ms)
`COGENT_CHAR_LIMIT`	`0`	Max message length (0 = unlimited)
`COGENT_STALE_TIMEOUT_MS`	`1800000`	Idle peer timeout before stale cleanup (30 min)
`COGENT_CLAUDE_PATH`	`claude`	Path to the Claude CLI executable
`COGENT_ENDPOINT`	not set	Cloud relay URL (e.g., `https://cogent.tools`). Enables cloud mode when set

COGENT — Powered by Essential AI Solutions Ltd. — cogent.tools