claude-profile

Sync your ~/.claude/ config across machines via a git-backed multi-profile system.

Status: v0.1.0 — early release. macOS + Linux only. Not yet on npm.

Docs: https://vshalpnjabi.github.io/claude-profile/ (deployed from main on every doc change)

Install

Until the package is published to npm, install directly from GitHub:

# Latest from default branch (main)
npm install -g github:vshalpnjabi/claude-profile

# Pinned to a release tag
npm install -g github:vshalpnjabi/claude-profile#v0.1.0

Or clone and link locally:

git clone https://github.com/vshalpnjabi/claude-profile.git
cd claude-profile
npm install && npm run build && npm link

Quickstart

Machine A (first machine)

# Create an empty private GitHub repo first (e.g., github.com/you/my-claude)
claude-profile init --git [email protected]:you/my-claude.git --profile default --activate
claude-profile install-skill   # wires SessionStart/Stop hooks for auto-sync

Machine B (second machine)

claude-profile init --git [email protected]:you/my-claude.git --profile default --activate
claude-profile install-skill
# ~/.claude/ now mirrors Machine A

See what's in a profile

claude-profile describe           # full sectioned report
claude-profile describe --brief   # counts only
claude-profile describe --json    # machine-readable

What gets synced

Synced by default (everything under ~/.claude/): settings.json, settings.local.json, CLAUDE.md, agents/, skills/, commands/, hooks/, output-styles/, plugins/ (including installed plugin code), statusline script, and 5 tracked keys from ~/.claude.json (mcpServers, autoUpdates, autoUpdatesProtectedForNative, showExpandedTodos, showSpinnerTree).

Never synced (per-machine state):

• Credentials and secrets — hard-blocked by built-in denylist: .credentials.json, *.key, *.pem, .env*, *secret*, *token*
• Caches: cache/, paste-cache/, downloads/, stats-cache.json, mcp-needs-auth-cache.json, plugins/cache/, plugins/plugin-catalog-cache.json, plugins/data/
• Per-machine runtime: daemon*, tasks/, telemetry/, jobs/, security/, security_warnings_state_*.json, *.bak.*, .last-cleanup
• Project + session history: projects/, sessions/, history.jsonl, file-history/, shell-snapshots/, session-env/
• ~/.claude/.claude-profile/backups/ (claude-profile owns this)
• Most top-level ~/.claude.json keys (oauthAccount, projects, theme, userID, firstStartTime, etc.) — run claude-profile describe to see the full list on your machine

You can override either list with a repo-root claude-profile.yaml:

include:
  - "**"
exclude:
  - "projects/**"
  - "sessions/**"

Commands

| Command | Purpose | |---|---| | claude-profile init --git <url> | Clone repo and register a profile on this machine | | claude-profile sync | Pull, merge, commit, push. Usually invoked by the hook | | claude-profile status | Show what sync would do; no writes | | claude-profile diff <path> | Unified diff between home and repo for one path | | claude-profile describe [name] | Inventory a profile: settings, hooks, MCP, commands, skills, agents, plugins, backups, and excluded ~/.claude.json keys | | claude-profile use <name> | Switch active profile (always backs up first) | | claude-profile list | List registered + repo-only profiles | | claude-profile adopt <name> | Snapshot current ~/.claude/ into a new profile | | claude-profile merge <source> --into <dest> | Merge profiles (prefer-dest | prefer-source | newer | mark-conflicts) | | claude-profile backups | List backup snapshots | | claude-profile restore <profile> [ts] | Restore a backup snapshot | | claude-profile prune [--keep N] | Delete old backups | | claude-profile config <op> [key] [value] | Per-machine config (get/set/unset) | | claude-profile install-skill | Install /profile skill + SessionStart/Stop hooks |

Auto-sync

install-skill wires two Claude Code hooks: a SessionStart hook that pulls the latest profile (3-second timeout, non-blocking) and a Stop hook that pushes any local changes in the background. Once installed you rarely need to run sync manually — changes flow between machines automatically each time Claude Code starts and stops.

Conflicts

When both machines edit the same file, the newer timestamp wins and the losing version is preserved at profiles/<active>/.conflicts/<path>.<host>.<ts> in the repo. No data is ever silently discarded.

Per-machine config

Machine-specific settings (which git remote to use, sync timeout, debounce window) live in ~/.claude-profile/config.json and are never committed to the repo. Manage with claude-profile config get/set/unset.

Docs

• Full documentation site (quickstart, command reference, sync algorithm, configuration, FAQ)
• Design spec

License

MIT — see LICENSE.