Skip to content

Quickstart

1. Install

npm install -g agentconf

Package and binary are both agentconf. Or clone and link locally:

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

2. Create a private repo

Create an empty private repo on GitHub (or any git host). Don't initialize it with a README — agentconf will populate it.

3. Initialize on Machine A

agentconf init \
  --git git@github.com:you/my-claude.git \
  --profile default \
  --activate

agentconf install-skill

What just happened:

  • The repo was cloned to ~/.agentconf/git/ (override with --path)
  • A new profile default was registered, and your current ~/.claude/ was adopted into profiles/default/ — filtered through the excludes and the credentials denylist, so secrets and caches never leave the machine
  • A first sync committed and pushed everything (including the tracked ~/.claude.json keys as claude.json.partial)
  • The /profile skill was installed with SessionStart (pull) and Stop (push) hooks wired into ~/.claude/settings.json

4. Initialize on Machine B

agentconf init \
  --git git@github.com:you/my-claude.git \
  --profile default \
  --activate

agentconf install-skill

~/.claude/ on Machine B now mirrors Machine A. From here, every time you start or end a Claude Code session on either machine, changes flow automatically.

5. See what's in your profile

agentconf describe              # sectioned human report
agentconf describe --brief      # counts only
agentconf describe --json | jq  # machine-readable

This reports settings, hooks, MCP servers, slash commands, skills, subagents, plugins, backups, and which ~/.claude.json keys are tracked vs excluded.

6. Daily life

You will rarely need to run anything manually after install — the hooks handle sync on every Claude Code session boundary. Useful ad-hoc commands:

agentconf status               # what would sync now? (read-only)
agentconf diff <relative-path> # unified diff for one file
agentconf sync                 # force a sync now
agentconf list                 # see all registered profiles
agentconf tui                  # browse every profile interactively
agentconf use work             # switch to a different profile

Next