Skip to content
FriendMachinePublic

About

Persistent memory for Claude Code and Codex. CLI, daemon, adapters, and hooks.

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Crosshead runtime

Persistent memory for Claude Code, Codex, Hermes, and OpenCode. This repository contains everything that runs on your machine: the crosshead CLI (xhd for short; onlybotsctl remains for existing scripts), the local daemon, the Claude Code, Codex, Pi, Hermes, and OpenCode adapters, and their lifecycle hooks. The hosted service at crosshead.sh is a separate codebase.

This client source is licensed under the Apache License 2.0. The separately operated hosted service is not part of this repository or that license. The Crosshead name and brand assets are covered by TRADEMARKS.md.

Install

Claude Code and Codex: plugin

claude plugin marketplace add FriendMachine/crosshead
claude plugin install crosshead@crosshead
# Codex:
codex plugin marketplace add FriendMachine/crosshead
codex plugin add crosshead@crosshead

Then start a session and run /crosshead:setup in Claude Code, or type $crosshead:setup in Codex. Only you can start setup; the model does not run it on its own. Until setup has run, each session starts with one line saying Crosshead isn't set up; nothing else happens and the session is never blocked. Setup asks where Crosshead should run and previews the directories, profiles, and files before applying the setup. In Codex, review the new project hooks in /hooks. The plugin launcher needs a POSIX shell.

The plugins are thin. They contain the lifecycle hooks, the setup skill and a small launcher that runs the installed runtime's hook entrypoints. They do not bundle, download or update the runtime, so one runtime, daemon and identity stays shared by every host. See host plugins.

Choose where Crosshead runs

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

Quickstart recommends the current project. Add more directories, opt into all projects, or choose manual commands only. Each directory can use Codex, Claude Code, or both, with an existing or new profile. Project hooks use their selected profile at startup and resume, including when the launcher skips direnv.

For scripts and agents, preview the same setup as JSON:

crosshead quickstart --scope project --workspace-root . --adapter both --profile work --dry-run --json

Use an existing profile name or pass --api-base https://crosshead.sh to create one. Apply by removing --dry-run. After starting a session, use crosshead workspace check to see the configured profile and observed startup and resume. Run the same check in an unselected directory to inspect its scope.

crosshead workspace add --workspace-root ../other-project --adapter codex --profile work
crosshead workspace list
crosshead workspace remove --workspace-root ../other-project

A bare crosshead quickstart in a terminal opens the setup wizard. Existing argument-based quickstart commands retain their legacy behavior; use an explicit --scope to select project, all-project, or manual setup from scripts.

The first workspace add on a legacy installation previews the change from user-wide coverage and asks before applying it. For noninteractive use, review --dry-run and pass --replace-user-hooks to acknowledge that coverage change.

Project setup writes local hook settings for each selected host when Git can confirm they are untracked. Both .codex/hooks.json and .claude/settings.local.json are excluded through Git's local info/exclude file. Tracked team settings stay intact. Non-Git projects, missing Git, and failed Git checks use private user hook registrations restricted to the selected directory; setup does not edit .gitignore. This fallback requires a host home outside the selected projects; setup refuses a destination inside a project before creating profiles or changing hooks. Existing user-wide Crosshead hook commands for this runtime are listed in the preview when setup replaces them. The runtime skips old Crosshead plugin and hook registrations after scoped setup. Review and restart host sessions after a scope change. Source excerpts are off for new bindings unless you choose --source-excerpts on. Checkpoints can still contain prompts and summaries.

Other hosts use crosshead quickstart --adapter pi|omp|hermes|opencode.

The installer downloads one release tarball, checks its SHA-256 against the installer script, installs the runtime npm dependencies with install scripts disabled, and writes the wrappers into ~/.crosshead/bin.

crosshead update --auto enables automatic updates on idle host launches (the default), checking for a new release about once an hour and retrying failed checks after 30 minutes. Before installing, Crosshead verifies GitHub's signed build attestation for the exact archive digest and this repository's release workflow. If verification or download fails, the host still launches and the update is retried later. If another install still holds the update lock and the launch check times out, launch is deferred; retry after the install finishes. crosshead update --manual disables automatic updates. crosshead update --policy shows the current setting. The older --pin option remains an alias for --manual.

For a manual install, obtain the digest from an independent release channel and run crosshead update --sha256 <digest>. Operator updates and rollbacks refuse to change runtime files while a host is running. Close host sessions first, or use --force at the end of the command to update during a session.

To check that a release matches this source, compare the installer's RELEASE_SHA256 with SHA256SUMS on the matching GitHub release. Public releases also carry GitHub build-provenance attestations; after downloading the install tarball, verify it with gh attestation verify <tarball> --repo FriendMachine/crosshead. Releases are reproducible: npm ci && npm run release:build at the tagged commit yields the same bytes (see Releases).

Choose what memory can retain

By default Crosshead keeps bounded task summaries, explicitly saved memory, and bounded excerpts of the workspace files and command output your agent reads while it works. The excerpts are what let a fresh session recover an exact specification or rule instead of a summary of it.

Those excerpts can be stored, synced through the configured service, and sent to a later coding-model session. Filters exclude some sensitive paths and credential-like text, but cannot guarantee that every secret is removed. If a repository contains text you do not intend to disclose through those paths, turn excerpt capture off before launching the host:

export CROSSHEAD_CAPTURE_SOURCE_EVIDENCE=0
codex  # or launch Claude Code from this shell

With capture off, memory still holds summaries and explicit writes, which can themselves contain code; this is not a guarantee that code never enters memory. Turning capture off does not delete existing memory. Verify a concrete rule in a fresh session after choosing either setting.

What runs locally and what is sent

  • Each agent has its own Nostr keypair, created locally. The private key stays in the runtime's local secret store under ~/.crosshead/config/secrets/. It signs authentication challenges, handoff capsules and trust receipts. Logs redact key material and session tokens.

  • The Crosshead plugin (or, without it, the adapter installer) registers Claude Code and Codex hooks. On session start and each turn, the hook asks the local daemon for context. After a turn, the daemon records where the work stands as hot memory and writes it to the hosted service. Promotion to warm memory and archiving to cold memory follow your memory mode (crosshead memory mode).

  • Hot-memory documents are signed by the local identity before upload and are ignored on read if the signature, identity, or scope does not verify. Bounded source-file capture follows each scoped binding's source excerpt choice. Legacy installs capture excerpts by default and accept CROSSHEAD_CAPTURE_SOURCE_EVIDENCE=0 to opt out.

  • Paid recall (warm and cold memory) is selected and assembled by the hosted service. This client sends the turn's goal and workspace scope, but no hosted response field is injected into an agent prompt. Only locally signature- verified hot memory remains available automatically; hosted recall can be inspected explicitly until a client-verifiable aggregation protocol exists.

  • Handoff capsules are signed, verified, and stored by the local runtime; the private key is never sent to the handoff service. To move work to another machine, write the capsule to a file and import it there:

    crosshead handoff export --source claude-code --target claude-code \
      --session-id <id> --prompt "<what to continue>" --output capsule.json
    crosshead handoff import --target claude-code --file capsule.json

    Export works with no network; it leaves out hosted memory references it cannot read and says so. --output will not replace an existing file unless you pass --force, and the file is readable only by you. Import saves the handoff to hot memory for the project that contains the current directory, so the next session there starts with it. Importing the same capsule again replaces the earlier copy instead of adding another. Without --target, export addresses the other host (Codex to Claude Code, or the reverse).

  • Import accepts a capsule signed by the profile's own key. A valid signature from any other key is rejected unless you pass --allow-signer <npub> for a key you trust. Capsules older than 30 days are rejected unless you pass --allow-stale.

  • Imported text is labelled as an imported handoff, not as something you saved yourself. It is not promoted to warm memory. Until the project records newer work (and for at most seven days) it is included in every prompt there.

  • crosshead status, crosshead doctor and crosshead logs show what the runtime is doing. Local state lives in ~/.crosshead/state/.

Set CROSSHEAD_PROFILE for explicit CLI commands. Legacy hooks retain their installed profile. ONLYBOTS_PROFILE is the legacy alias. Explicit CLI --profile takes precedence. Scoped hooks use the profile selected during setup. Use crosshead memory mode off --profile <name> to stop automatic memory hooks for that profile. Other hosts retain a mode-off notice and administrative diagnostics without injecting recalled memory. Use crosshead workspace remove to detach a project.

Without a connection

Setup does not need the hosted service to be reachable. If crosshead.sh cannot be reached (a sandbox with restricted egress, a CI job, a laptop offline), the profile is still created and setup prints registration: deferred with the network error (--json output carries registrationDeferred and registrationDeferredReason). Capture and recall work locally at once, and the profile tries to sign in on its next hosted request. That sign-in can still be refused; crosshead doctor reports a profile that has never signed in and why.

Setup still fails when the problem is the address rather than the network: a response that refuses the sign-in, a redirect, a certificate error, a refused connection to this machine (localhost, 127.0.0.1), a proxy asking for credentials or failing upstream, or (for any --api-base other than crosshead.sh) a host name that does not exist. A proxy that refuses the destination (HTTP 403) counts as unreachable; Node uses HTTPS_PROXY only when NODE_USE_ENV_PROXY=1 is set, and otherwise connects directly. A proxy that intercepts TLS and answers with its own page or certificate is not recognised and fails setup; use the local-only profile below in that case.

For a profile that never contacts a hosted service, pass --api-base http://127.0.0.1:0. Hot memory, hooks and handoff capsules work; hosted recall, sync between machines and billing do not.

Local-only checkpoints are stored per profile. A legacy flat store remains readable for its sole existing local-only profile, whose identity is pinned before creating another profile. If several profiles already shared an unowned store, or profile metadata cannot establish its owner, review the files in state/local-hot-memory/*.json to establish ownership. Scoped setup retains matching subdirectory and symlink history. Its preview shows adoption of earlier unscoped checkpoints when one project is selected for an existing profile. Eligible local history is copied into current workspace partitions before a new session writes them. Once a scope is replaced, its flat archive stays available for recovery and no longer participates in recall. Later unscoped captures require an explicit workspace.

If workspace settings are damaged, crosshead workspace list, workspace check, and doctor report the problem while automatic memory stays paused. Run:

crosshead workspace repair --dry-run
crosshead workspace repair
crosshead quickstart --scope project --adapter both --profile work

Install, update, rollback, and uninstall validate workspace policy before changing installation files or stopping a daemon. A damaged policy requires explicit repair first; the running installation is left intact.

Repair preserves the exact damaged policy in a private adjacent backup and sets manual scope. It keeps memory files and host settings intact. Review the new setup before enabling automatic hooks again. doctor also reports missing project directories without dropping the remaining runtime diagnostics.

crosshead uninstall removes the runtime. Uninstall the plugin (claude plugin uninstall crosshead@crosshead, codex plugin remove crosshead@crosshead) to remove its hooks; crosshead uninstall claude-code and crosshead uninstall codex remove installer-written hooks and adapter files.

Hermes and OpenCode

Install the host first, then use a native Crosshead plugin:

crosshead quickstart --api-base https://crosshead.sh --adapter hermes --workspace-root .
# Or:
crosshead quickstart --api-base https://crosshead.sh --adapter opencode --workspace-root .

For an existing Crosshead profile, use crosshead install hermes or crosshead install opencode. Restart the host to load the plugin. Both share the local daemon and workspace memory with the existing adapters. See native host setup and verification for custom homes, uninstall commands, supported versions, and Docker tests.

Repository layout

Path Contents
src/runtime/ CLI, daemon, host adapters, hooks, hosted API client
plugins/, .claude-plugin/, .agents/plugins/ Claude Code and Codex plugins and their marketplace, generated by npm run plugins:generate
src/protocol/ Wire contract shared with the hosted service. It depends only on Node built-ins and is published as @crosshead/protocol.
schemas/ Published JSON schemas for protocol records
tests/ Unit tests. Client/server contract tests run in the hosted repository against the exact release artifact.
scripts/ Boundary check, release build and release verification

See docs/ARCHITECTURE.md for the boundary with the hosted service, compatibility rules and how both sides stay in sync.

Develop

Node 22.23.4+, 24.22.1+, or 26.12.1+ (older releases contain known remotely exploitable Brotli and HTTP client vulnerabilities).

npm ci
npm run typecheck
npm run check:boundary
npm test             # builds first; tests spawn the compiled daemon and hooks
npm run plugins:check

npm test works after a clean checkout and npm ci; no separate build is needed. Run npm run build before invoking Vitest or the plugin checks directly.

Releases

npm run release:build                    # builds dist/ and release/
node scripts/verify-release.mjs --smoke  # digests, layout, content scan, smoke install

release/ then contains:

  • crosshead-runtime-install-<version>.tgz: the tarball crosshead.sh/install serves. Its layout (package.json, package-lock.json, dist/runtime/*.js) is fixed by already-installed clients.
  • crosshead-runtime-<version>.tgz: npm package @crosshead/runtime.
  • crosshead-protocol-<version>.tgz: npm package @crosshead/protocol.
  • crosshead-release.json: version, release ID, source commit and digests.
  • SHA256SUMS.

Pushing a v<version> tag runs the release workflow, which rebuilds, verifies and attaches these files to a GitHub release. The hosted service vendors a verified release; see docs/ARCHITECTURE.md.

Public service advertisements and work opportunities use NIP-99 listings.

About

Persistent memory for Claude Code and Codex. CLI, daemon, adapters, and hooks.

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages