Commands

agentconf exposes 17 commands. Run any with --help for full options.

Setup

init

Clone a repo and register a profile on this machine.

agentconf init --git <url> --profile <name> [--activate]

• --git <url> — git remote URL (required on the first init on this machine; afterwards defaults to the configured remote)
• --profile <name> — profile name (required; created if missing in repo)
• --activate — set as active profile on this machine
• --path <dir> — checkout location (defaults to the configured checkout path, or ~/.agentconf/git for the first init on this machine)

install-skill

Install the /profile slash command and wire SessionStart/Stop hooks for auto-sync.

agentconf install-skill [--no-hook]

• --no-hook — install only the skill, skip hook installation

Daily sync

sync

Pull, merge, commit, and push the active profile. Usually invoked automatically by the hooks.

agentconf sync [--profile <name>] [--dry-run] [--quiet] [--background]
                    [--pull | --push]

• --profile <name> — sync a non-active profile (repo-only fetch + pull, no home writes)
• --dry-run — print plan; no writes
• --pull / --push — internal hook entry points

status

Show what sync would do; no writes.

agentconf status [--profile <name>]

diff <path>

Unified diff between ~/.claude/<path> and profiles/<active>/<path> for a single file.

agentconf diff settings.json

tui

Interactive three-pane browser for everything in your profiles: profiles │ categories (Overview, Settings, Hooks, MCP servers, Commands, Skills, Agents, Plugins, Output styles, Backups) │ items with full wrapped detail — skills, hooks, MCP servers, commands and agents are shown by name with complete descriptions.

agentconf tui

Keys: ↑/↓ (or j/k) move, ⏎/→ drill in, esc/← back out, g/G top/bottom, PgUp/PgDn scroll detail, r refresh.

Actions on the selected profile: u switch to it (y/N confirm), S sync it, d delete it — d asks local vs remote; a remote delete requires typing the profile name, exactly like agentconf delete --remote. Results appear in the footer.

Without a TTY (piped output, CI) it prints every profile's full report sequentially, as before.

describe [name]

Inventory everything in a profile.

agentconf describe              # active profile
agentconf describe work         # named profile
agentconf describe --brief      # counts only
agentconf describe --json       # machine-readable

Reports:

• Profile metadata — name, active/registered, host, repo, branch, last commit, last sync
• Sync rules — include/exclude/denylist counts, tracked-file totals + top-dir breakdown
• Settings (settings.json + settings.local.json) — model, permissions, env, statusLine, outputStyle
• Hooks — grouped by event with matcher + handler type
• MCP servers — name, transport, source file
• Slash commands (with descriptions)
• Skills (with descriptions)
• Subagents (with descriptions)
• Plugins
• Output styles
• Tracked + excluded ~/.claude.json keys (excluded shown with size)
• Backups — count + newest + oldest

Profile management

use <name>

Switch the active profile. Always backs up ~/.claude/ first.

agentconf use work

list

List all profiles — registered on this machine + repo-only.

agentconf list

adopt <name>

Snapshot the current ~/.claude/ into a new (or existing) profile in the repo.

agentconf adopt work [--overwrite] [--switch] [--no-push]

• --overwrite — replace an existing profile
• --switch — activate the new profile after adopt
• --no-push — commit but don't push

merge <source> --into <dest>

Merge one profile into another using a chosen strategy.

agentconf merge personal --into work --strategy newer

Strategies:

• prefer-dest (default) — keep dest on conflict
• prefer-source — overwrite dest with source on conflict
• newer — newer mtime wins
• mark-conflicts — copy both to .conflicts/ for manual resolution

Other options:

• --dry-run — print plan, no writes
• --no-apply — skip post-merge sync into ~/.claude/ when dest is active
• --no-push — commit but don't push

delete <name>

Delete a profile from this machine; with --remote, also from the sync repo (and therefore the git remote and every other machine). Never touches ~/.claude/ — it removes agentconf's copy of the profile, not your live agent config.

agentconf delete <name> [--remote] [--force] [--yes] [--purge-backups]

• Local (default): unregisters the profile and removes its per-machine sync baseline. Backups are kept unless --purge-backups.
• --remote: additionally deletes profiles/<name>/ from the repo, commits, pushes, and writes a .deleted/<name> tombstone so other machines stop syncing it — their next sync auto-unregisters it, or aborts with instructions if it is their active profile. Prompts for the profile name unless --yes. Aborts if the remote is unreachable, and if the push fails it aborts before changing anything locally so a re-run can retry.
• --force: required to delete the active profile; clears the active slot (run use <other> afterwards — autosync hooks stay quiet until then).
• Resurrect a deleted profile with agentconf adopt <name> — it clears the tombstone in the same commit.

Note: --remote removes the profile from the branch tip; its content remains in git history (see the FAQ).

Backups

backups

List backup snapshots.

agentconf backups [--profile <name>]

restore <profile> [ts]

Restore a backup snapshot. If ts is omitted, restores the newest.

agentconf restore personal                  # newest
agentconf restore personal 2026-05-26T03-31 # specific

prune

Delete old backups, keeping the N most recent per profile (default 10).

agentconf prune [--keep <N>] [--profile <name>]

Config

config <op> [key] [value]

Per-machine config in ~/.agentconf/config.json. Not committed to the repo. get prints the resolved value through all layers (defaults < repo YAML < profile YAML < machine overrides); machine keys (git, path, active, profiles, host) live top-level, anything else in dot notation becomes a per-machine override of the YAML config.

agentconf config get                  # machine + full resolved config
agentconf config get git.push        # → true (default)
agentconf config get git.push --explain   # → true (default)
agentconf config set git.push false  # per-machine override
agentconf config set autosync.push_debounce_seconds 30
agentconf config unset autosync.push_debounce_seconds

Internal

autosync

Deprecated stub. The SessionStart/Stop hooks now invoke sync --pull and sync --push directly.