Workspaces and profiles

A workspace tells Crosshead where you’re working. A profile tells it which agent identity and memory to use. One profile can serve several repositories.

On this page

Choose which projects use Crosshead

This project
Enable Claude Code or Codex hooks in the selected project. Add other projects when you want them connected.
All projects
Enable hooks for the selected tools wherever you start them. Working memory is still scoped by workspace.
Manual commands only
Configure an identity without automatic Claude Code or Codex workspace hooks.

Guided crosshead quickstart previews where hooks will run. For a project-scoped setup, this example adds Codex to another repository using an existing default profile. Use both to connect both hosts. Remove --dry-run to apply after reviewing the preview.

crosshead workspace add --workspace-root ~/work/another-repo --adapter codex --profile default --dry-run

If you want to switch from all projects to an allowlist, run crosshead quickstart and choose This project. workspace add is for adding to project scope. When moving from a legacy user-wide install, review the preview for hooks that setup will replace.

Create a profile when you need another identity

Use the same profile when you want Claude Code and Codex to pick up the same work. Add a profile if you want a distinct identity and memory, for example to keep a client’s projects under a different key. Different Git repositories already get their own working-memory scope, even on the same profile.

During guided setup you can enter a new profile name. To create one separately, use keygen --setup. This example creates studio and keeps the existing CLI default. Replace the example name with your own. Profile creation does not attach a folder.

crosshead keygen --setup --profile studio --api-base https://crosshead.sh --no-default --create-only

Use a different profile below a folder

In Crosshead 0.5.1 or later, you can set an override for an existing directory under project or all-project setup. New versions leave your profile selection as it was until you set an override.

Crosshead checks the session’s directory and its parents. The closest configured override wins, including within nested Git repositories. Without an override, the hook uses the profile chosen when it was set up.

Suppose all projects normally use default. You want everything under ~/work/studio to use studio, with one client under ~/work/studio/client-a using client-a. Create both profiles first, then configure and inspect the overrides.

crosshead workspace profile set --workspace-root ~/work/studio --profile studio
crosshead workspace profile set --workspace-root ~/work/studio/client-a --profile client-a
crosshead workspace check --workspace-root ~/work/studio/client-a

A session launched in ~/work/studio/service uses studio. One launched in ~/work/studio/client-a/api uses client-a. With project-only hooks, this rule applies only where a hook already runs. Assigning a folder changes which profile the hooks use. It leaves your coding tools’ own settings and chat history in place.

Restart the host after changing an override and check the profile in the new session. Old memory stays with the identity that captured it. To inspect it, run crosshead memory hot --profile default, substituting the previous profile if needed. Switching profiles does not copy memories or credits. To remove the more specific override and inherit studio again, run:

crosshead workspace profile clear --workspace-root ~/work/studio/client-a

Check which profile is active

crosshead workspace list
crosshead workspace check
crosshead status

workspace list shows your bindings and folder overrides. Run workspace check from the exact directory where you launch the host. Compare the configured profile with the Crosshead attached message in a fresh session and the startup observation in workspace check.

For ordinary inspection commands, --profile takes precedence, followed by CROSSHEAD_PROFILE, then any folder override, then the CLI default. Project hooks follow their binding and folder override. If crosshead status and the session show different profiles, check those CLI overrides and use --profile to inspect the identity you intended.