Install Crosshead and check your first handoff

Before you start

You need Node.js 22 or newer, npm, curl and tar on macOS or Linux, plus an installed Claude Code or Codex CLI. Run these commands from your project directory. Crosshead creates an agent identity and starts a local daemon; keep its private key private.

Install and connect your host

The installer checks the release checksum before unpacking. You can read the installer first.

curl -fsSL https://crosshead.sh/install | bash

export PATH="$HOME/.onlybots/bin:$PATH"

Choose the host you use. For Claude Code:

crosshead quickstart --api-base https://crosshead.sh --adapter claude-code --workspace-root "$PWD"

For Codex:

crosshead quickstart --api-base https://crosshead.sh --adapter codex

For Codex, launch through the managed codex wrapper on your PATH so the adapter can attach. See the Codex guide for wrapper details. Claude Code uses project hooks; see the Claude Code guide.

Verify memory in a fresh session

crosshead status
crosshead doctor
crosshead memory hot --scope all --json

1. In the connected agent, investigate a small task and state one precise finding, such as the test command and its observed result.
2. Finish the turn normally so the adapter can save working state.
3. Open a fresh session in the same repository with the same Crosshead profile. Ask it to continue that task and identify the saved finding.
4. Compare the answer with the hot-memory output and the actual repository. Memory is context to verify, not proof that a test passed.

Hot memory is free. Hosted context packs and other paid operations use prepaid credits; the runtime can fall back to free hot-memory context when funding is unavailable. See pricing before enabling paid workflows.

Stay current or pin a release

Managed launchers check for a new stable release at most once every 12 hours, after other managed sessions finish and pending memory writes drain. Older installations need one manual crosshead update to receive this behavior.

For a reproducible setup, run crosshead update --pin. Restore automatic updates with crosshead update --auto, or inspect the setting with crosshead update --policy.

If the finding is missing

Check that the daemon is running, the adapter is installed, and both sessions use the same repository and identity. After a restart, run crosshead start. Inspect all runtime scopes: an empty shared document does not mean the Claude Code or Codex document is empty. Review crosshead logs for hook or authentication errors.

The standard installer sets up managed runtimes. The separate Cursor MCP setup requires a built MCP bridge and is not bundled with this installer. To update a managed installation, run crosshead update.

Keep going

All memory guides · Read the eval · Install Crosshead