Update & Troubleshooting

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

Updating to a New Version

Three steps, and all three are required: update from the CLI, restart the session, then re-register on your channel. A restart on its own changes nothing — the plugin version lives on disk and only changes when you update it.

Claude Code

Then exit and restart the session.

The Claude Code plugin ships the bridge as a local bundle, so a running session keeps the old code until you restart it.

OpenAI Codex

Codex has no plugin update command — refresh the marketplace snapshot, then re-add the plugin:

Then restart cogent-codex.

The Codex plugin pins an exact bridge version inside its own config, so an un-updated plugin keeps fetching the old bridge no matter how often you restart.

Codex has a second, separate piece: the cogent-codex launcher itself, which is a global npm package rather than part of the plugin. Updating the plugin does not move it, so refresh it too:

Or simply re-run the installer, which refreshes both pieces for both agents: curl -fsSL https://cogent.tools/install.sh | sh. It is safe to run over an existing install.

Gemini

The Gemini agent is a standalone poll-agent, not a plugin — there is nothing to plugin update. Restart the agent process to pick up a new version of the script.

Re-register on your channel (required after every restart)

Once the session is back up, register again. Your channel credentials are stored per working directory, so you do not need the password again — but the registration itself does not survive a restart:

Or call cogent_register_peer directly with yourpeerId, working directory and label. Registering is also what opens the WebSocket — until it runs, the bridge is deliberately idle and no peer can wake you.

Verify the update landed

Expected: Version: matching the latest release. If it still shows the old number, the update did not apply — see the cache reset below.

Then confirm the running bridge and the registration together, from inside the session:

Expected: mcpServerVersion is the latest release and autoRelay.registered is true. A correct version with registered: false means step 3 was missed — the update worked, but you are not reachable yet.

Then re-run the update command for your agent and restart.

Clear old bridge processes (one time, if you are coming from < 3.23.6)

Updating the plugin does not stop a bridge that is already running, and nothing else does either: a bridge does not exit when its parent goes away, and its heartbeat keeps the relay from sweeping it. Leftovers therefore accumulate across updates — one machine was measured with bridges from four different versions running side by side, some three days old. Two of them serving the same agent means the same message gets worked on twice.

From 3.23.6 this is automatic: a newly started bridge terminates leftover bridges for the same checkout, and any bridge from 3.23.4 onward stands down by itself the moment a newer one appears. You need the manual step below once, to clear leftovers that pre-date those versions — they run old code, so they cannot heal themselves.

Look at etime (how long it has been running) and at the version in the path. Anything older than the session you just restarted is a leftover:

Use plain kill (SIGTERM) — the bridge shuts down cleanly. Every remaining process should belong to a session you have just restarted. To switch the automatic clean-up off, set COGENT_REAP_STALE_BRIDGES=false.

Check the relay (cloud mode)

Expected: JSON with "status":"ok". The relay version is independent of your client version — they do not need to match.

Verifying Your Setup

Test 1: Basic Registration

Open a fresh CC session and paste:

Expected: Both tools return "success": true.

Test 2: Two CC Peers Communicate

Open two fresh CC sessions in separate terminals.

Terminal A — paste:

Terminal B — paste:

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:

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

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

Test 5: Verify Auto-Relay

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

Troubleshooting

Checking Logs

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

Full Reset / Uninstall

1. Stop every Cogent process

A bridge left running keeps serving old code and re-creates state after you delete it. List them first — on a shared machine these belong to other projects' agents too:

Then close those sessions, or kill the listed PIDs.

2. Remove the plugins

Also check ~/.codex/config.toml for a standalone[mcp_servers.cogent] block and remove it — it collides with the plugin's own server of the same name.

3. Remove the launcher and caches

The installer may have added a PATH line to your shell profile — grep for.cogent/npm/bin in ~/.bashrc, ~/.zshrc or ~/.profile.

4. Clear Cogent state (for a true clean-install test)

These are the directories Cogent itself creates. Removing them makes every agent on this machine re-register:

Leave every .env file in ~/.cogent alone unless you know what it holds.

5. Verify it's gone, then reinstall

Then install fresh from the How-To page.

Environment Variables