Configuration & layout

~/.agentsync/ is just files. Use the CLI or edit them in $EDITOR — both are first-class. There is no hidden internal representation: the TOML structs that parse these files are the canonical model.

Directory layout

• Directory~/.agentsync/

  • agentsync.toml agents, update defaults, secrets backend, [memory] banner
  • Directorymcp/

    • github.toml one MCP server per file
  • Directorylsp/

    • gopls.toml one LSP server per file
  • Directorysubagents/

    • reviewer.md one subagent per file
  • Directorycommands/

    • review.md one slash command per file
  • Directoryhooks/

    • PreToolUse.toml one hook per file
  • Directorymarketplaces/

    • anthropic.toml one marketplace per file
  • Directoryplugins/

    • atlassian.toml one plugin enablement per file
  • Directorymemory/

    • AGENTS.md canonical memory
    • Directoryfragments/ reusable @import pieces

      • …
  • Directoryskills/

    • Directorymy-skill/ a skill is a directory, not just SKILL.md

      • SKILL.md required metadata + instructions
      • Directoryscripts/ optional bundled code (kept verbatim, +x preserved)

        • …
      • Directoryreferences/ optional bundled docs

        • …
      • Directoryassets/ optional templates / data (binary OK)

        • …
  • Directorysecrets/

    • secrets.age age-encrypted vault
  • ignore.toml paths reconcile should stop tracking
  • Directory.state/ machine-local bookkeeping (gitignored)

    • …

Override the directory’s location with AGENTSYNC_HOME.

agentsync.toml

The top-level config: which agents are registered, update defaults, and the secrets backend.

~/.agentsync/agentsync.toml

# Registered agents and whether each is enabled. Each agent is its own
# [agents.<name>] sub-table (a TOML table keyed by agent name), not an
# array-of-tables.
[agents.claude]
enabled = true
scope   = "user"   # display-only; the file an entry lives in is the scope of record

[agents.opencode]
enabled = true

# Plugin update defaults (used by `agentsync plugin outdated` / `plugin upgrade`).
[updates]
default_mode     = "track"   # pinned | track | manual — a plugin's own `update`
                             # wins; this is the fallback. Only "track" plugins are
                             # auto-bumped; "pinned"/"manual" need explicit action.
                             # Unset behaves as "track".
default_interval = "24h"     # configured update cadence

# Secrets backend — see the Secrets guide.
[secrets]
backend       = "age"
file          = "secrets/secrets.age"                # vault path; relative → under
                                                     # ~/.agentsync, default shown
recipient     = "age1…"                              # public key, safe to commit
identity_file = "${env:HOME}/.config/agentsync/age.key"  # private key, per-machine

# Memory rendering options.
[memory]
banner = true   # default; set false to omit the managed-file banner from
                # rendered memory files (CLAUDE.md, AGENTS.md, …)

[updates] sets the default plugin-update policy for agentsync plugin outdated / agentsync plugin upgrade --all. default_mode is pinned (never auto-bump), track (auto-bump to the latest marketplace version), or manual (bump only on explicit action); a plugin’s own update key overrides it, and an unset default_mode behaves as track. default_interval (e.g. "24h") is the configured update cadence for plugins that opt in to periodic updates.

[secrets].file is the path to the age-encrypted vault. A relative path is resolved under ~/.agentsync/ (honouring AGENTSYNC_HOME); an absolute path or one with a leading ~ / ${env:HOME} is expanded as written. When omitted it defaults to secrets/secrets.age, so most configs can leave it out. See the Secrets guide.

The [memory] banner notice that agentsync prepends to each rendered memory file points edits back at .agentsync/memory/AGENTS.md + agentsync apply. It lives only in the rendered file (stripped on capture, never written to your canonical source) and is on unless you set banner = false. See the memory guide.

Note

Use the CLI (agentsync agent add, agentsync secret set, …) and let it write these files, or hand-edit them — agentsync re-reads the files either way. The exact key set is validated by agentsync check and surfaced by agentsync doctor.

Per-component files

File	Holds
mcp/<name>.toml	one MCP server (guide)
lsp/<name>.toml	one LSP server
subagents/<name>.md	one subagent (the directory is subagents/, not agents/ — agents names the harness registry in agentsync.toml)
commands/<name>.md	one slash command
hooks/<event>.toml	one hook
marketplaces/<name>.toml	one marketplace (guide)
plugins/<id>.toml	one plugin enablement (guide)
memory/AGENTS.md + fragments/	canonical memory (guide)
skills/<name>/	one skill directory per the Agent Skills spec — SKILL.md plus any bundled scripts//references//assets//nested files, all carried verbatim
secrets/secrets.age	the age-encrypted vault (guide)

Project overlay

A repo can carry a project source tree — a .agentsync/ directory at its root with the same layout as the user tree above (scaffolded by agentsync init --scope project), minus .state/. It overlays onto your user config: a project entry replaces a user entry with the same id/name, new entries are appended, and project memory is appended after user memory. The project’s [agents] table is authoritative — project scope renders only to the agents the project declares (agentsync agent add <name> --scope project), never the user’s enabled agents, and a project that declares none is a hard error. Commit the .agentsync/ tree to share it with collaborators. See Project-local config.

State

~/.agentsync/.state/ is gitignored machine-local bookkeeping: the last-applied hashes (targets.json) that make drift detection possible, the apply lock, the two-phase write staging dir, first-apply backups, and the marketplace/plugin cache. Keys are stored ${HOME}-relative so state is portable across machines.