Features

A tour of everything claude-nomad does, current as of v0.62.6. The first two sections are the reason the tool exists; the rest is the safety net and day-to-day tooling around them.

Sessions follow you across machines

Claude Code stores every conversation in a folder named after the project’s absolute file path. The same project usually lives at a different path on each machine (/Users/you/project on a Mac, /home/you/project on Linux), so a transcript copied verbatim is invisible to claude --resume on the other host.

claude-nomad fixes this with path remapping: a small path-map.json file in your sync repo records where each project lives on each machine, and every pull rewrites the transcripts for the host you are on. Start a conversation on your desktop, run nomad sync on each machine, and claude --resume on your laptop picks it up as if it never left. See How it works for the mechanics.

One shared setup, per-machine exceptions

Your skills, slash commands, rules, statusline, and global CLAUDE.md live once in the sync repo. Slash commands, rules, statusline, and CLAUDE.md are symlinked into ~/.claude/; skills are copy-synced (gsd-owned gsd-* skills excluded). On native Windows, where symlinks need Developer Mode or admin rights, the symlinked names are real copies instead and nomad push captures your edits. Edit a skill anywhere and every machine gets it on the next pull. (agents/ and hooks/ are intentionally left to gsd; see GSD-aware sync.)

Settings are smarter than a straight copy: every pull regenerates ~/.claude/settings.json by merging a shared base file with a per-host override file. One machine can run a different model, point at a different MCP URL, or set extra environment variables without forking the rest of your setup. Scalars and objects merge; arrays and null replace. Because the file is regenerated on every pull, host-specific edits belong in the override file, not in ~/.claude/settings.json itself.

What syncs, and what never does

Sync is allow-list driven: only paths claude-nomad knows about ever leave the machine. Credentials, OAuth state, MCP runtime state, shell history, and per-host local settings are on a hard never-sync list (the authoritative list is NEVER_SYNC in src/config.ts) and are blocked even when they appear nested inside a directory you opted into syncing. Projects not listed in path-map.json are left alone in both directions.

Opt-in per-project extras

Beyond transcripts, a project can opt in to syncing named extras such as its .planning/ directory, its own project-local <repo>/.claude/ config directory, or a project-level CLAUDE.md. (That project .claude/ next to your code is distinct from the global ~/.claude/ in your home folder, which claude-nomad already syncs.) Only whitelisted names are eligible, and projects that do not opt in are untouched. The .claude/ extra is filtered so only config travels (settings.json, hooks/, agents/, skills/, commands/, rules/); host-local and ephemeral state (settings.local.json, session transcripts, caches) is stripped on push. Opt a name in only when your project git-ignores it: if .claude/ is committed to the project repo, the repo already syncs it, and adding nomad on top would clobber the committed copy. See Usage for how to opt a project in.

If you run GSD (@opengsd/gsd-core), the .planning overlay sync and the handling of gsd-owned files are wired for you out of the box. See GSD-aware sync for the details.

Every push is secret-scanned

Conversation transcripts can contain pasted API keys, tokens, and passwords. Before anything is published, nomad push scans the exact files about to leave the machine with gitleaks and aborts on any hit. When something is found, an interactive menu lets you redact the secret in place, allow a false positive, drop the session from the push, or skip and decide later. There is also a standalone nomad redact for transcripts already committed, nomad drop-session to pull a session out of a pending push, and an overlay file for your own allowlist entries. See Recovery flows and Security for the full story.

Preview before you trust it

nomad diff shows, offline and without locks, what a pull would change. --dry-run on both pull and push prints the full plan (symlink moves, settings diff, transcript overwrites) without writing anything. Nothing has to be taken on faith.

One command tells you what is wrong

nomad doctor is a read-only health check covering the things that actually break: a sync repo stuck mid-rebase, hook references pointing at scripts missing on this host, hooks that would crash at session start because a Node script under a synced directory needs --preserve-symlinks-main, a settings.json that no longer matches the base+host merge nomad would write (settings drift, reported in both directions: keys missing locally point at nomad pull, local-only additions point at nomad capture-settings), a missing git committer identity in the sync repo (a push fails at commit time without one), path-map entries whose local project folder no longer exists on this host, synced skills you have edited locally, version drift between your install and the latest release, gitleaks drift against CI, and a backup cache that needs pruning. Each failing line carries a fix hint, and extra flags go deeper: --check-shared secret-scans what a push would publish, --check-schema validates your settings against the live Claude Code schema, and --check-remote confirms the remote still has a valid shared/ and path-map.json before you pull. See Commands for every check.

Self-healing sync, with backups

Every file a pull or push would overwrite is copied into a timestamped local backup first, and nomad clean --backups prunes old snapshots when they pile up. If a conflicted pull ever leaves the sync repo wedged mid-rebase, nomad pull --force-remote recovers automatically: it parks your stranded commits on a branch, resets to the shared state, and re-pulls, refusing entirely if any shared config would be lost. See the FAQ for the recovery walkthrough.

Easy on, easy off

nomad init creates the private GitHub repo, scaffolds it, and disables GitHub Actions on it so no CI ever runs against your conversation history; --snapshot seeds it from the machine you are on. nomad adopt <name> moves a pre-existing ~/.claude/<name> shared dir into the repo and replaces it with a managed symlink, and nomad update upgrades the CLI in place.

Leaving is just as transparent: everything claude-nomad manages in ~/.claude/ is plain files and symlinks, with no proprietary format to export from. Transcripts and settings.json are real files that keep working untouched. To walk away, run nomad eject: it replaces every managed symlink with a real dereferenced copy in one step, so your setup keeps working after you delete the ~/claude-nomad/ checkout and uninstall the CLI. (On native Windows, where synced names are already real copies, adopt copies back a real copy and eject has almost nothing to materialize.) After ejecting, it prints a checklist of the remaining manual steps (uninstall, remove the env vars, optionally delete the repo and backup cache). See Commands for the full flag reference.