FAQ¶

Will my credentials end up in the repo?¶

No. .credentials.json and a set of secret-name patterns are hard-blocked by BUILTIN_DENYLIST in src/core/config.ts. The denylist is unioned in at resolve time and no user config can remove it. Even if you accidentally add .credentials.json to include:, it stays out of the repo.

What about my project history?¶

~/.claude/projects/, sessions/, history.jsonl, and the related per-machine state dirs are excluded by default. They're large, change constantly, and would create conflicts on every sync.

The same goes for the projects key in ~/.claude.json — it's not in the default claude_json.include_keys list.

Why git instead of Dropbox / iCloud / rsync?¶

Versioned — every change is a commit with a timestamp and host stamp.
Conflict-safe — git already knows how to handle concurrent edits, plus agentconf preserves the loser at .conflicts/<path>.<host>.<ts>.
Auditable — git log -p profiles/personal/settings.json shows exactly who changed what, and when.
Branchable — keep experimental configs on a branch.

Can I keep different settings on different machines?¶

Yes. Three ways, ranked by scope:

Profile — agentconf use work swaps the active profile entirely.
Machine config — agentconf config set writes to ~/.agentconf/config.json which is never committed. Useful for git.pull_strategy, autosync.push_debounce_seconds, etc.
settings.local.json — ~/.claude/settings.local.json syncs by default, but most users keep it machine-specific by adding it to exclude: in the profile's agentconf.yaml.

What happens if two machines edit the same file?¶

The newer mtime wins, and the older version is preserved at profiles/<active>/.conflicts/<path>.<host>.<iso-ts>. The sync exits with status 1 so you know to inspect. See How sync works.

Can I disable auto-sync?¶

Yes:

agentconf config set autosync.enabled false

Or remove the hooks from ~/.claude/settings.json (they have stable IDs agentconf-pull and agentconf-push). You can always run agentconf sync manually.

How do I migrate from another machine?¶

# On the new machine
agentconf init --git <url> --profile default --activate
agentconf install-skill

init will check out the repo and run an initial sync. Your ~/.claude/ will be populated from profiles/default/. Existing files are backed up to ~/.agentconf/backups/default/<ts>/ first.

How big can the repo get?¶

Excluding project history and caches keeps things small. A typical profile is a few MB at most. The plugins directory is the biggest variable — set limits.marketplaces_warn_mb (default 50) if you want a warning when it crosses a threshold.

How do I see what changed in the last sync?¶

cd "$(agentconf config get path)"   # the checkout
git log -5 --stat                         # recent sync commits

Why does sync exit with code 1?¶

Code 1 means conflicts were written to .conflicts/. Inspect and resolve manually. Code 2 means another sync is already running (lock held).

Can I use this without GitHub?¶

Yes — any git remote works (GitLab, Bitbucket, Gitea, self-hosted). Just pass the URL to --git.

Does delete --remote remove the profile from git history?¶

No — it deletes the profile from the branch tip and tombstones it; old commits still contain the content. If you deleted a profile because it held secrets, rewrite history with git filter-repo on the sync repo (e.g. git filter-repo --path profiles/<name> --invert-paths) and re-clone on every machine, or rotate the secrets.

Where is everything stored?¶

Path	Contents
`~/.claude/`	The live Claude Code config (the thing being synced)
`~/.agentconf/config.json`	Per-machine config (git URL, path, active profile, host)
`~/.agentconf/backups/<profile>/<ts>/`	Pre-`use` backups
`~/.agentconf/sync.lock`	Sync lock file
`~/.agentconf/last-sync.timestamp`	Last successful sync ISO
`~/.agentconf/last-push.timestamp`	Push debounce file
`~/.agentconf/logs/<date>.log`	Background sync logs
`<checkout>/profiles/<name>/`	Mirrored profile contents
`<checkout>/profiles/<name>/.conflicts/`	Loser versions from conflicts
`~/.agentconf/state/<name>/meta.json`	Per-machine sync baseline (content hashes; never committed)
`<checkout>/agentconf.yaml`	Repo-level config (optional)
`<checkout>/profiles/<name>/agentconf.yaml`	Profile-level config (optional)