agent-profile

Sync your AI coding agent configs across machines via a git-backed multi-profile system.

Supports Claude Code (~/.claude/) today; OpenAI Codex CLI (~/.codex/) and Gemini CLI (~/.gemini/) support is planned next (see Scope).

Status: v0.2.0 — early release. macOS + Linux only.

Formerly claude-profile — renamed when the scope grew beyond Claude Code.

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

Install

npm install -g @vishalpunjabi/agent-profile

The package is named @vishalpunjabi/agent-profile on npm (the unscoped agent-profile belongs to an unrelated package). The installed binary command is agent-profile.

Alternative (clone + link):

git clone https://github.com/vshalpnjabi/agent-profile.git
cd agent-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)
agent-profile init --git [email protected]:you/my-claude.git --profile default --activate
agent-profile install-skill   # wires SessionStart/Stop hooks for auto-sync

Machine B (second machine)

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

See what's in a profile

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

Scope

agent-profile is growing from a Claude Code–only tool into a config sync layer for the major AI coding agent CLIs:

| Agent | Config location | Status | |---|---|---| | Claude Code | ~/.claude/ + tracked ~/.claude.json keys | ✅ Supported | | OpenAI Codex CLI | ~/.codex/ | 🚧 Planned | | Gemini CLI | ~/.gemini/ | 🚧 Planned |

The model stays the same for every agent: one private git repo, multiple named profiles, per-agent include/exclude rules, a hard-blocked credentials denylist, and content-hash change detection with newer-wins conflict resolution (losers always preserved). Everything below currently describes the Claude Code integration.

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/.agent-profile/backups/ (agent-profile owns this)
• Most top-level ~/.claude.json keys (oauthAccount, projects, theme, userID, firstStartTime, etc.) — run agent-profile describe to see the full list on your machine

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

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

Commands

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

Docs

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

License

MIT — see LICENSE.