Configuration

agentconf resolves config from 5 layers, lowest-priority first:

1. Built-in defaults (src/core/config.ts)
2. Repo-level — agentconf.yaml at the repo root (committed)
3. Profile-level — profiles/<name>/agentconf.yaml (committed)
4. Machine-level — ~/.agentconf/config.json (per-machine, never committed)
5. Env + flags — env vars (AGENTCONF_QUIET=1) and CLI flags

Each layer fully replaces arrays (no concat). Objects are deep-merged.

The denylist is the exception — the built-in denylist is always unioned in. Users can extend it but never remove built-in entries.

Defaults

include:
  - "**"            # everything in ~/.claude/

exclude:
  # Per-machine cache + transient runtime
  - "cache/**"
  - "daemon*"
  - "daemon/**"
  - "tasks/**"
  - "telemetry/**"
  - "jobs/**"
  - "backups/**"
  - "paste-cache/**"
  - "downloads/**"
  - "file-history/**"
  - "shell-snapshots/**"
  - "session-env/**"
  - ".last-cleanup"
  - "stats-cache.json"
  - "mcp-needs-auth-cache.json"
  - "security/**"
  - "security_warnings_state_*.json"
  - "*.bak.*"
  # Project + session history
  - "projects/**"
  - "sessions/**"
  - "history.jsonl"
  # Plugin caches (plugin code itself does sync)
  - "plugins/cache/**"
  - "plugins/plugin-catalog-cache.json"
  - "plugins/data/**"

denylist: []        # extended with BUILTIN_DENYLIST at resolve time

claude_json:
  path: "~/.claude.json"
  partial_filename: "claude.json.partial"
  include_keys:
    - "mcpServers"
    - "autoUpdates"
    - "autoUpdatesProtectedForNative"
    - "showExpandedTodos"
    - "showSpinnerTree"

autosync:
  enabled: true
  pull_on_session_start: true
  push_on_session_stop: true
  pull_timeout_seconds: 3
  push_debounce_seconds: 10
  pull_command: "agentconf sync --pull --quiet"
  push_command: "agentconf sync --push --quiet --background"
  hook_id_pull: "agentconf-pull"
  hook_id_push: "agentconf-push"

git:
  pull_strategy: ff-only   # ff-only | rebase | merge
  push: true
  commit_message_template: "sync from {host} at {iso_ts}"
  commit_author_from_git: true

backups:
  dir: "~/.agentconf/backups"
  keep_per_profile: 10
  use_hardlinks: true
  auto_prune_on_use: true

limits:
  marketplaces_warn_mb: 50

log:
  level: info               # debug | info | warn | error
  color: auto               # auto | always | never

Overriding

Repo-wide (everyone gets this)

Commit agentconf.yaml at the repo root:

git:
  pull_strategy: rebase

claude_json:
  include_keys:
    - mcpServers
    - autoUpdates
    - theme           # additional

One profile only

Commit profiles/<name>/agentconf.yaml:

exclude:
  - "plugins/heavy-plugin/**"

Just this machine

Use agentconf config set <key> <value>:

agentconf config set autosync.push_debounce_seconds 30
agentconf config set git.pull_strategy rebase
agentconf config get

These land in ~/.agentconf/config.json and are never committed.

Built-in denylist

These patterns block credentials and secrets at the lowest layer. No user config can remove them.

.credentials.json
*.credentials.json
*.key
*.pem
*.p12
.env
.env.*
*secret*
*token*

If you try to include .credentials.json via include: it will still be filtered out by the denylist.

Env vars

Var	Effect
HOME	Override home root (rarely useful)
AGENTCONF_HOME	Override ~/.agentconf/ location (used by integration tests)
AGENTCONF_QUIET=1	Set log.level=warn for the run