Troubleshooting

CoCo runs on Linux and macOS. These checks cover common problems with the current repository version and its tested Codex 0.160.1 setup.

Check your setup

coco doctor

Get a short report about your installed commands, connection, repositories, worktrees, saved conversations, and available resource controls. Problems include a suggested next step. It also detects a coordinator left running from another installation or using different settings.

You can run it from any directory, even before starting cocod. Checks that need the coordinator are skipped when it is unavailable. Doctor leaves your workspaces unchanged and does not start agents or repair anything.

For the individual checks and selected executable paths, use coco doctor --json. Review local paths and workspace names before sharing that report. Credential contents, conversations, and raw command errors are not included. Checks have time limits; a partial report says what could not be checked. See diagnostic options for exit codes and collection limits.

CoCo cannot connect

Start the coordinator in another terminal:

cocod

Leave it running while using CoCo. If it reports another coordinator already owns your workspaces, use that existing process.

Installation or Codex startup fails

Check codex --version and coco --version. CoCo needs a configured Codex command on PATH. If it is elsewhere, set COCO_CODEX_BINARY=/absolute/path/to/codex in both the coordinator’s environment and the terminal running coco jump.

Cargo builds need Rust 1.98.1 or newer plus a C compiler and linker. On macOS, install the Command Line Tools. Nix installation supplies the build toolchain.

Workspace execution cannot start

If CoCo reports that Codex cannot start a workspace’s execution process, restart the coordinator with:

COCO_WORKSPACE_EXECUTION=shared cocod

This compatibility mode provides shared execution without per-workspace resource measurements or limits.

If the error is specifically about creating a systemd scope, use:

COCO_WORKSPACE_CONTAINMENT=process-tree cocod

This keeps separate execution processes and basic measurements, but cannot enforce resource limits. Stop any active work before restarting the coordinator.

A repository or branch is rejected

The repository needs at least one commit. Check:

git status --short
git log -1 --oneline

An existing branch must not already be checked out elsewhere. Carrying local changes requires the new base to equal the source checkout’s current commit. See Choose code and context.

A workspace name is ambiguous

Select its repository explicitly:

coco ../api jump fix/login

Use coco list -a --json to find full workspace IDs, which resolve from any directory.

An agent is already working

Follow its state with coco status fix/login -f, or use coco jump fix/login to enter the conversation. Wait until it is ready before another send; messages are not queued behind an active turn.

Prepared or unloaded workspaces

Prepared means the checkout is available and work has not begun. Use send or jump to begin. If you enter a fresh Codex UI and leave without taking an action, the workspace stays prepared.

An unloaded thread is a saved conversation waiting to be opened, commonly after restarting cocod. send or jump loads it when needed.

A named profile changed

Restore the original settings in $CODEX_HOME/<name>.config.toml, normally under ~/.codex, or create a new workspace with a new profile. CoCo refuses to reopen a conversation using changed named-profile settings. Comments and formatting can change. See Models and profiles.

The coordinator stopped during work

Start cocod again, then inspect the workspace with status or jump. The workspace, files, and saved conversation remain available. An active turn was interrupted and does not resume automatically; review where it stopped before sending a new instruction.

Old pending decision IDs and responses retained for send --wait are no longer available. Read the saved conversation through jump.

After a forced kill, some execution processes may remain until the next coordinator start. Linux cgroup cleanup handles those on restart; the process-tree fallback cannot reliably clean up detached descendants.

A send result is uncertain

Inspect the workspace with status or jump before sending again. If CoCo returned an operation ID, retry the same message with that ID to avoid starting duplicate work:

coco send fix/login "The original message" --operation-id <id> --wait

Use the exact original message and workspace. See Workspace commands for retry behavior.

Context copying failed during creation

Check coco status <workspace> before creating again. If a failed workspace exists, its files remain available, but CoCo will not copy the source again automatically. Keep any files you need, then delete the failed workspace before retrying creation.

If the source has no finished turn yet, let its first turn finish and retry.

If CoCo reports that an older conversation has no usable fork boundary, finish a new turn in that source with your current Codex version, then retry. That new turn lets CoCo copy the earlier conversation too.

Close or delete is blocked

Finish active work, answer pending requests, close the attached Codex UI, and stop background commands using the checkout. Commit, stash, or move local files you need. CoCo also protects ignored files.

Keep or merge commits that would lose their last branch or tag. For detached work, create a retaining branch or tag before closing. See Review and clean up for retention and discard options.

If another workspace or conversation depends on the thread, keep it with --keep-thread or finish the dependants first. For a prepared workspace that needs the context, start it first so its conversation can be copied.

If cleanup was interrupted, inspect the reported remaining resources and retry delete. If the workspace remains in Deleting, restart cocod and check again. A changed plan requires a fresh review.

A custom guard can also block cleanup; CoCo displays its reason. Inspect the loaded rules with coco hook list.

Resources or cost are unavailable

Resource measurements are Linux-only. Enforced limits additionally require cgroup v2 and a compatible systemd user session. limits show reports support and any changes waiting to take effect.

Cost depends on Codex providing an estimate. A dash is an unavailable value; saved token reports after a restart may be marked last seen. See Resource accounting.

Codex UI compatibility

With the tested Codex 0.160.1 setup, the UI’s !command shortcut is unavailable for CoCo’s default workspace execution. Run ad-hoc commands in a separate shell at the worktree path shown by coco status <workspace>.

Immediately after loading or copying a conversation, send a normal prompt before using /review or /compact. CoCo uses experimental Codex features, so different Codex versions can change compatibility.

If decide cannot present a request type, it leaves the request pending. Use jump to inspect it in Codex.

Data and privacy

Saved conversations are kept by Codex and code changes by Git. CoCo keeps workspace details and operational history locally. It temporarily holds recent final responses for send --wait; secret decision answers are hidden and not retained.

An MCP application can read repository paths, diffs, workspace details, and saved signals. Connect applications you trust with that data. Signals remain saved after workspace deletion, subject to their retention limit.

Hooks and guards run as your user and can access your files. Use trusted commands, keep secrets out of signal payloads, and avoid recursive hooks.