Troubleshooting

For the previous product direction, see v2.4 original docs and migration.

A documented feature is missing, or a command is unavailable

Check the installed version. Web 3.0.2 includes Git Changes/review, Custom Terminals, notifications, Timeline, Health and native Codex recovery; earlier packages may lack these additions. Verify npm dist-tags rather than assuming that your installed version or latest matches the current source.

npx @hogancv/coordinate-agents@latest --version
# From a source checkout, after npm ci:
node bin/coordinate-agents.mjs web --root "/path/to/project" --port 3000

npm 3.x exposes Web/help/version only. doctor, install, config, task, quickstart, and inspector require the GitHub Plugin, source Legacy entry, or npm 2.4.0. Do not install npm latest as a repair for a missing Plugin runtime.

The server cannot start or the port is busy

Check Node.js >=18, Git, a regular non-symlink project directory, and dependency installation (npm ci for source). Use --port 0 to choose a free port instead of terminating an unrelated process. Inspect the printed error and selected --root; a non-Git startup folder initializes Git and Workspace storage.

An agent command is missing or cannot log in

Run codex --version and agy --version, or the two configured Custom commands, in the environment used to launch Web. Settings accepts executable names or absolute paths, without inline flags or shell syntax. Correct the selected project's settings and explicitly create/restart a task; running CLIs are not reconfigured in place. Custom restarts retain their task's command snapshot.

Executable detection does not verify login, provider access, model health, or quota. Open that CLI directly to fix its own authentication/configuration; do not copy credentials between agents. If Node cannot load the native dependency in source, rerun npm ci for the current Node version.

Terminal display or resize is limited

Check Session diagnostics for backend. Native PTY availability depends on platform and Node version. Node 18 retains owned-stdio fallback; it is not a real terminal and cannot provide native TUI or child-observed resize. On Windows Node >=20, a disposable detached Session Host probes real TTY behavior before selecting the native backend. Fallback requires confirmed owned-process cleanup. An actual Session failure does not automatically retry a task. Fix the cause and use explicit restart; do not resend implementation instructions blindly.

A task is quiet or the timeline has no DONE

Expand the timeline and inspect formal receipts plus linked Session facts. SENT means input was dispatched; ordinary output or idle does not mean done. Health silence hints identify missing observable progress, not proven failure. A pending wait should continue with its returned cursor/revision, not repeat send. History from versions that did not record events cannot be backfilled. Custom tasks have no default cooperation rounds or reports.

Review feedback or a Custom prompt cannot be sent

For Default review feedback, ensure Codex is at a blank input prompt and confirm readiness for each send. Switching files, refreshing the diff, or closing the Changes drawer during preflight cancels pending feedback. Custom tasks can view and copy diffs but do not support Send to Codex.

For a Custom prompt, check the CLI accepts multiline bracketed paste, then confirm readiness in its preview. Closing the preview cancels pending delivery; uncertain or already dispatched input is not retried automatically. Copy and paste manually when readiness is unknown.

A desktop notification is missing

Use current source on Windows 10/11 or macOS; Linux is unsupported. Enable and save the selected project's notification preferences. Check the chosen events: APPROVED and FAILED are selected by default, DONE is optional. Use Send test notification, then check OS permissions and Focus / Do Not Disturb. An accepted OS command is not proof the notification appeared on screen.

Only formal persisted Default receipts trigger notifications. Keep backend, agent processes, and the interactive OS session running. Browser close is fine; Custom output, Session exits, archive, and idle are not notification events. At-most-once dispatch means failed or interrupted attempts are not retried. Changing a summary does not resend; a new round can notify again.

A closed browser left agents running, or a project disappeared

Independent Session Hosts can outlive the browser and Web server. Reopen Web and use explicit terminal-close controls. Archiving closes related terminals and hides records, while retaining source files. Archived projects stay hidden until you explicitly add the same folder again. Clearing archived conversations is permanent and removes their timeline history.

Structured Plugin / Legacy troubleshooting

The remaining sections apply to the optional GitHub Plugin and Legacy runtime, not npm 3.x Web. Use node bin/coordinate-agents-legacy.mjs from source or pin npm 2.4.0. See Structured workflow and Legacy installation.

Plugin-first diagnosis and structured errors

Start with the Plugin-facing Task and setup surfaces rather than inspecting queue files manually:

The Plugin path does not require a global npm CLI. Every Skill calls the active payload through:

node "<skill-dir>/../coordinate-agents/scripts/runtime-entry.mjs" <command> ...

If this resolver reports PLUGIN_RUNTIME_NOT_FOUND, verify that the Plugin is enabled in the current Codex installation and start a new thread; do not infer that coordinate-agents must be added to PATH. The resolver accepts cached Git marketplace installs, personal local marketplace roots, and Windows paths with spaces. The npm command examples below are standalone/debugging fallbacks.

npx @hogancv/coordinate-agents@2.4.0 setup --json
npx @hogancv/coordinate-agents@2.4.0 task status --json
npx @hogancv/coordinate-agents@2.4.0 status --json
npx @hogancv/coordinate-agents@2.4.0 agent doctor --json

The JSON contract keeps runtime facts separate from Skill explanations. Common codes include EXECUTABLE_NOT_FOUND, EXECUTABLE_NOT_RUNNABLE, SPAWN_FAILED, AGENT_EXIT_NONZERO, AGENT_TIMEOUT, AUTH_REQUIRED, TASK_NOT_FOUND, TASK_STATE_CONFLICT, and STALE_CLAIM. Authentication is classified only when the coding CLI explicitly reports login/authentication failure. A non-zero exit or timeout stops the current activation; it is not an automatic retry signal. After fixing the reported executable or runtime issue, use task resume only when the user explicitly asks to continue.

task dispatch is the only Plugin-facing action that sends IMPLEMENT and launches the Implementer. It resolves the workflow Agent and final command, checks the Adapter and executable, and fails closed before transport when the command is unavailable. A missing command therefore produces Task ERROR with EXECUTABLE_NOT_FOUND, no queued IMPLEMENT, and no child process. After the user fixes the command, task resume is required before another dispatch.

NOTE

This guide covers common issues with host Skill installations, the default Codex and Antigravity reference adapters, .agent-bus recovery, and dynamic agent registration via agent doctor.

Start with the same package version and target used for installation:

npx --yes @hogancv/coordinate-agents@2.4.0 doctor --codex
npx --yes @hogancv/coordinate-agents@2.4.0 doctor --antigravity

Preserve redacted output and the exit status. Do not paste credentials or force a destructive repair.

Skill not discovered

Observed behavior: mentioning collaboration does not trigger $coordinate-agents, or the CLI says the Skill is unavailable.

1. Run selected-target doctor and note the exact Skill path.
2. Confirm the terminal uses the same CODEX_HOME or Antigravity home that was installed.
3. Restart the CLI so it reloads Skill metadata.
4. Explicitly invoke $coordinate-agents once to separate discovery from installation failure.

If doctor reports a missing or invalid copy, reinstall only the selected target. Do not copy the other CLI's credential directory.

Codex App selects the wrong project or cannot start the Implementer

In Codex App, add or open the target Git repository and set the thread project/workspace path to the repository root—the directory containing .git. Start a new thread and invoke $coordinate-agents. The App path does not require manually opening two CLI windows, but the Runtime still opens a project-scoped persistent Session for the Implementer locally. Configure the actual executable command, not a role label:

# Antigravity
npx @hogancv/coordinate-agents@2.4.0 config set agent.antigravity.command agy

# Claude Code as a registered custom agent
npx @hogancv/coordinate-agents@2.4.0 agent add claude --adapter generic-cli --command claude \
  --args '["--print", "{prompt}"]'

Use git rev-parse --show-toplevel to compare the repository root with the App project path. Use doctor to inspect the final resolved command and executable status. A project-path error and an executable-command error are independent; fix both if necessary. Verify the selected CLI's own --help output before copying its prompt or directory flags; the runtime already uses the project root as the child process working directory. Alternatively, ask the active Codex App thread:

Use $coordinate-agents to configure Claude Code as the Implementer for this project. Inspect the
installed `claude` executable and `claude --help`, register it with `generic-cli`, run `doctor`, and
show me the resolved configuration. Do not start until I confirm.

Workspace settings support Antigravity prompt mode or automatic approval. The adapter default is --dangerously-skip-permissions; explicit saved argument arrays take precedence. The published npm 2.4.0 runtime requires the explicit permission configuration shown below. The legacy one-shot path passes configured args and then adds --prompt-interactive <prompt>; a persistent Session starts with --prompt-interactive= for current agy parsers, then writes its first instruction through the PTY unless {prompt} is explicitly configured. If agy --help confirms --dangerously-skip-permissions and the user explicitly wants it, configure that argument in Workspace settings or set agent.antigravity.args with config set; config list shows the saved user arguments, while doctor checks the executable/version only.

If a Windows PowerShell proxy reports flag needs an argument: -prompt-interactive, the wrapper may have dropped a standalone empty argument. Persistent Antigravity sessions use the single argument --prompt-interactive= to preserve the empty value through that forwarding step. Restart the Web server after updating the source, then explicitly restart the failed task pair; no automatic retry is needed.

Node version too low

Node.js 18+: missing or requires attention

Run node --version. Install a supported Node.js LTS from an official source, open a new terminal, and check that PATH resolves the new executable. The package refuses to claim support below Node 18.

codex or agy is not found

Codex CLI: missing or requires attention
Antigravity CLI (agy): missing or requires attention

Run where codex / where agy on Windows or command -v codex / command -v agy on POSIX. Install the missing native CLI from its official source, authenticate it, and prove a native model response before rerunning doctor. A selected-target check fails when that target CLI is absent; the unselected CLI is informational only. For native Antigravity, configure agy directly; its global proxy settings apply without a project-specific wrapper:

npx @hogancv/coordinate-agents@2.4.0 config set agent.antigravity.command agy
npx @hogancv/coordinate-agents@2.4.0 doctor

The project-level command in .agent-bus/config.json takes precedence over this user setting.

Implementer stops with ERROR

launch performs an executable check before starting the Implementer. A missing command, unsafe Windows entrypoint, spawn failure, non-zero child exit, or conversation/runtime failure is fatal for the current activation. Inspect the reported Agent, Adapter, configured command, error code, and .agent-bus/logs/*-ERROR.json artifact. Do not keep polling or automatically resend IMPLEMENT; fix the command/runtime and explicitly launch again when ready. Coordinate Agents does not perform login-status or provider-health preflight checks.

Unknown installation directory

Codex: installation invalid (unrecognized installation), path: ...
Manual action required; inspect or back up the existing directory before using: ... install ...

The target may be a source checkout, a hand-installed Skill, or user data. The installer refuses to overwrite it because a forged metadata file is not proof of ownership. Inspect and back up the directory. Use --force only after the user explicitly accepts replacement or deletion of that exact path.

doctor fails after installation

One or more dependencies or installations require attention.

The lines above the summary identify the failing component. Check the command's exit status, verify the suggested repair matches the actual platform and package manager, apply one repair at a time, and rerun the identical doctor command. Linux repair commands are suggestions to review, not a guarantee that a distribution repository supplies Node 18+.

Message remains in processing

First confirm the worker process is gone; recovering active work can duplicate implementation.

node <skill>/scripts/agent-bus.mjs status --root <repo>
node <skill>/scripts/agent-bus.mjs recover --agent antigravity \
  --stale-after-seconds 14400 --root <repo>

recover moves only stale claims back to new according to the requested threshold and current lease state. Rerun status, then let exactly one worker call wait. Never manually copy a message between queue folders while a worker is alive.

.agent-bus is damaged or unsafe

Possible errors include malformed message quarantine, invalid state records, or refusal of an unsafe path. Stop both agents. Preserve the directory for diagnosis, inspect quarantine/ and status, and verify .agent-bus is a normal directory inside the Git root—not a symlink, junction, hard-linked leaf, or path escape. Use recover only for intact stale claims. Use clean only with explicit confirmation after saving required specs, reviews, and evidence.

Do not repair YAML frontmatter or move queue files by hand unless you can prove no process holds a claim; manual edits destroy evidence lineage.

Windows path normalization

Symptoms include the two agents reporting different roots, a copy-pasted command breaking at spaces or &, or prompts being created in an unexpected checkout. Always run quickstart from the actual Git worktree root and copy the generated launch commands unchanged. They encode root paths with --root-base64 rather than embedding an unsafe shell string. Compare:

git rev-parse --show-toplevel
npx --yes @hogancv/coordinate-agents@2.4.0 doctor

Do not manually translate C:\project to /mnt/c/project unless both CLIs execute in WSL. Windows and WSL paths that refer to the same files are still different process environments.

npm registry metadata is inconsistent

npm ERR! code ETARGET
npm ERR! notarget No matching version found for @hogancv/coordinate-agents@<version>

Compare the public metadata without changing credentials:

npm view @hogancv/coordinate-agents dist-tags.latest version repository.url --json
npm config get registry

The repository must be https://github.com/hogancv/coordinate-agents and the registry should be the intended public npm registry. A stale mirror may lag the release. Do not downgrade silently, switch to an untrusted registry, or run a GitHub checkout as an installer. Wait for consistent metadata or use an already verified stable exact version.

See the canonical bilingual AI installation guide and the security boundary.