Skip to content
agent-bridge

Troubleshooting

  • Console windows flash on Windows while Codex works. This happens when Codex runs your session inside its background app-server daemon: that process has no console, so Windows opens a new window for every git or node process it starts. Add daemon_auto_start = false under [features] in ~/.codex/config.toml, run codex app-server daemon stop, and restart Codex.
  • Codex subagents misbehave after an update of Codex. Since 0.11.0 agent-bridge runs Codex subagents through codex app-server (so they can receive messages while they work). Set AGENT_BRIDGE_CODEX_EXEC=1 to go back to codex exec; subagents then only see messages after they finish. Codex versions without app-server fall back to exec automatically.
  • Claude was not woken for a finished subagent. Claude Code occasionally does not turn a background wake-up into a turn. Since 0.17.0 each turn end starts two waiting hooks: if a wake-up is not followed by any activity within 20 seconds, the second one tries again, and it also wakes the session for results that arrive when nothing else waits. Results stay unread until the session really shows activity, so they arrive with your next message at the latest. Auto-wake is remembered per session, also across /reload-plugins and restarts.
  • A peer shows up as plain codex with the plugin folder as its cwd. Codex hasn’t reported the project directory yet. It does so on the first hook or tool call; make sure the hooks are trusted in /hooks.
  • Messages to an idle agent are not answered. Exact direct messages use wakeOnDirect by default when a supported native transport is attached. Other messages need the listen window, auto-wake or Claude channels. A missing Codex thread identity, detached TUI or unsupported queue leaves mail unread until the next prompt or inbox call. See delivery and wake requirements; inbox storage and queue acceptance do not prove consumption.
  • Claude shows “agent-bridge: listening for replies from peers” for minutes. That was the listen window holding the turn open while background subagents ran (before 0.9.0). Update and restart the session: the turn now ends immediately and the session is woken when a result arrives.
  • A relay subagent (agent-bridge:codex, agent-bridge:opencode) does not answer status questions. It is waiting for its one call and cannot reply until it returns. Call peers instead: it shows the delegation’s runtime and current step.
  • A delegated task restarts from scratch. That was the 15-minute limit before 0.5.2. Update, and restart the calling session.
  • “version mismatch” / a session cannot join. Incompatible wire protocols use separate brokers; compatible retained versions can keep working together. Update the tools, check status, and adopt the selected version at a convenient reload or next server start. See updating.
  • Codex update fails with “Access is denied”. Legacy native cache pruning could hit files held by running sessions. The current bridge updater retains immutable versions and changes selectors for future starts. Keep active sessions and jobs running, inspect doctor, and follow the reported recovery command. Dirty or divergent marketplace clones are refused and preserved; see update limits and recovery.