agentconf

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.4.0 — early release. macOS + Linux only.

Formerly claude-profile, then briefly @vishalpunjabi/agent-profile — now agentconf.

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

Install

npm install -g @vishalpunjabi/agentconf

The npm package is @vishalpunjabi/agentconf (npm blocks the unscoped name as too similar to the unrelated agent-conf). The installed binary is agentconf.

Alternative (clone + link):

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

Machine B (second machine)

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

One profile, many machines. Use the same --profile name on every machine and let auto-sync reconcile them (newer-wins; losing versions are preserved under .conflicts/). Do not adopt a new profile name per machine — that creates parallel profiles (personal, personal_temp, …) that you then have to merge by hand. If a machine's ~/.claude/ already has content you want to keep, run init then adopt <name> --overwrite into the shared name so it merges into one history. Reserve merge for genuinely combining two different profiles (e.g. work into personal), not two snapshots of the same one.

See what's in a profile

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

Scope

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

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

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

Commands

| Command | Purpose | |---|---| | agentconf init --git <url> | Clone repo and register a profile on this machine | | agentconf sync | Pull, merge, commit, push. Usually invoked by the hook | | agentconf status | Show what sync would do; no writes | | agentconf diff <path> | Unified diff between home and repo for one path | | agentconf describe [name] | Inventory a profile: settings, hooks, MCP, commands, skills, agents, plugins, backups, and excluded ~/.claude.json keys | | agentconf tui | Interactive three-pane profile browser (skills/hooks/MCP/agents by name) with use/sync/delete actions | | agentconf scan [profile] | Scan a profile's JSON configs for embedded secrets (warn-only; --json, --strict) | | agentconf use <name> | Switch active profile (always backs up first) | | agentconf list | List registered + repo-only profiles | | agentconf adopt <name> | Snapshot current ~/.claude/ into a new profile | | agentconf merge <source> --into <dest> | Merge profiles (prefer-dest | prefer-source | newer | mark-conflicts) | | agentconf delete <name> | Delete a profile (local; --remote also from the sync repo + tombstone) | | agentconf backups | List backup snapshots | | agentconf restore <profile> [ts] | Restore a backup snapshot | | agentconf prune [--keep N] | Delete old backups | | agentconf config <op> [key] [value] | Per-machine config (get/set/unset) | | agentconf 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.

Secrets

agentconf's denylist blocks credential files, but secrets can also hide inside tracked configs (an API key in settings.json env, an MCP server's env block). scan, and the warnings shown on adopt/sync/describe, flag these (warn-only — they are not removed). Rotate anything exposed, and suppress reviewed values with secrets.allow in agentconf.yaml (by key name or sha256:<fingerprint>).

Per-machine config

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

Docs

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

License

MIT — see LICENSE.