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
  • Directoryagents/

    • 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.
[[agents]]
name    = "claude"
enabled = true

[[agents]]
name    = "opencode"
enabled = true

# Secrets backend — see the Secrets guide.
[secrets]
backend       = "age"
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, …)

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 secrets 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 verify and surfaced by agentsync doctor.

Per-component files

File	Holds
mcp/<name>.toml	one MCP server (guide)
lsp/<name>.toml	one LSP server
agents/<name>.md	one subagent
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.