Troubleshoot Crosshead
Work through setup, capture, and recall in order. The first step that fails usually tells you where to look.
The crosshead command is missing
export PATH="$HOME/.crosshead/bin:$PATH"
command -v crosshead
node --versionIf the command is still missing, check the installer output and verify you are in the shell where you set PATH. Use the supported Node.js versions. If you intentionally installed in a custom home, use its bin directory instead.
The session never attaches
crosshead workspace check
crosshead status
crosshead doctorRun the checks from the same directory and shell environment you use for the host. workspace check tells you whether hooks apply to Claude Code or Codex there. Check the host home too, especially if you launch with CODEX_HOME or CLAUDE_CONFIG_DIR. In Codex, review /hooks and start a fresh session after trusting hooks.
If the daemon is stopped, run crosshead start and check again. If you use an older managed Codex wrapper setup, use command -v codex and compare the result with the path shown during setup. Check crosshead logs for hook and authentication errors.
The tool attaches but the turn is missing
Confirm the session’s profile and memory mode. Finish a small test turn with a specific finding, then inspect the correct profile with crosshead memory hot --scope all. If it is empty, check the completion hook and the daemon logs. A process interrupted before the turn finishes may have no completed checkpoint.
If you are moving across machines, run crosshead memory sync on the source to check for pending writes, the last successful sync, and safe error codes. A local checkpoint can be available immediately while a destination machine is still waiting for the upload.
The turn is saved but the new session misses it
- Check the receiving session’s working directory, profile, and startup report. See how to resolve a profile mismatch.
- On a second machine, check that the profile has the same identity and API origin, and that both checkouts resolve to the same workspace.
- Ask about the task by name and compare the reply against the saved checkpoint. The prompt brief has room for recent relevant context. Older details may need an explicit search or a written handoff.
Get help
Check service status if authentication or sync fails. When you contact support, include your OS, host, Crosshead version, selected profile, what you expected, and the relevant lines from crosshead doctor or crosshead logs. Review the output for private paths, keys, and project text before sending.