Project-local config

A repo can carry its own project source tree: a .agentsync/ directory at its root with the same on-disk layout as your user ~/.agentsync/. Commit it to the repo to share the project’s agent config with collaborators — when they clone and apply, they get the project’s servers, plugins, and memory layered onto their own user config.

Scaffold the project tree

cd ~/code/myrepo
agentsync init --scope project        # creates ./.agentsync/

Or target a specific path (this implies project scope):

agentsync init --project ~/code/myrepo   # creates ~/code/myrepo/.agentsync/

Caution

--scope user together with --project is an error. A git-URL clone argument is only supported at user scope.

That writes a tree with the same files as the user tree — agentsync.toml plus mcp/, lsp/, skills/, agents/, commands/, hooks/, memory/ (with fragments/), plugins/, and secrets/:

• Directorymyrepo/

  • Directory.agentsync/

    • agentsync.toml [agents] table (the project’s own agent set — required)
    • Directorymcp/

      • company-api.toml project-only MCP servers
    • Directoryplugins/

      • screenshot.toml disable a user plugin here
    • Directorymemory/

      • AGENTS.md project memory (+ fragments/)
    • Directoryskills/

      • …
    • Directoryagents/

      • …
    • Directorycommands/

      • …
    • Directoryhooks/

      • …
    • Directorylsp/

      • …
    • Directorysecrets/

      • …

The one difference from the user tree: there is no .state/. Apply records state centrally under ~/.agentsync/.state/, keyed by the project root.

Author the tree

The project’s enabled agents go in an [agents] table. This declaration is authoritative: project scope renders only to the agents declared here — never your user-scope agents — so every collaborator gets the same render from the same committed source. Declaring at least one agent is required; every scope-aware render path (apply, status, diff, reconcile, update --apply, verify) refuses to run against a project that declares none.

myrepo/.agentsync/agentsync.toml

[agents]
claude = { enabled = true }       # the agents THIS project renders to

The ergonomic way to manage it is the agent commands at project scope:

agentsync agent add claude --scope project      # or --project <path>
agentsync agent list --scope project
agentsync agent disable claude --scope project

A project-only MCP server is just an mcp/<id>.toml file, identical in format to a user-scope MCP file:

myrepo/.agentsync/mcp/company-api.toml

[server]
type    = "stdio"
command = "npx"
args    = ["-y", "@company/mcp"]

Turn off a user-level plugin for this repo with a plugins/<id>.toml:

myrepo/.agentsync/plugins/screenshot.toml

[plugin]
disabled = true

Author project memory directly in memory/AGENTS.md (compose it from fragments/ just like the user tree):

myrepo/.agentsync/memory/AGENTS.md

# Project conventions

Run `just test` before pushing.

How the overlay merges

The project tree is overlaid onto your user canonical:

• a project entry replaces a user entry with the same id/name,
• new project entries are appended,
• project memory is appended after user memory,
• the project’s [agents] table is authoritative — user-scope agents are never inherited, and a project that declares none is a hard error (fix it with agentsync agent add <name> --scope project). import --scope project stays available before any agents are declared, so you can bootstrap the tree from native config first.

User-level servers and plugins still apply unless the project replaces or disables them.

Apply from inside the repo

Project scope is an explicit opt-in — pass --scope project (which walks up from cwd to the .agentsync/ tree):

cd ~/code/myrepo
agentsync apply --scope project   # walks up to the .agentsync/ tree
ls .mcp.json                      # project-scope MCP servers landed (repo root)

Import a project’s native config

Already have native project-scope config (e.g. <root>/.claude/, or a <root>/.mcp.json from claude mcp add --scope project)? Capture it straight into the project tree:

cd ~/code/myrepo
agentsync import claude --scope project        # → ./.agentsync/
agentsync import claude --project ~/code/myrepo # explicit root

This reads the agent’s native project-scope config and writes it into <root>/.agentsync/, seeding central state with the project scope + root so the next apply doesn’t foreign-collide.

Plugins are user-scope only

Plugin import is user-scope only across the harnesses: a named import claude:plugin:<name> --scope project errors, and a bulk import claude:plugin --scope project silently skips.

Choosing a scope

Commands default to user scope; project scope is always an explicit opt-in:

agentsync apply --scope user             # user config (the default)
agentsync apply --scope project          # walk up from cwd to the .agentsync/ tree
agentsync apply --project ~/code/myrepo  # point at a specific repo

If you run a command with no scope inside a project tree, agentsync prompts you to choose project-vs-user (there is no default — you pick). In a non-interactive shell, or with the global --no-input flag, it errors instead of guessing. And --scope project/--project with no .agentsync/ tree is a hard error pointing at agentsync init --scope project — never a silent fall back to user scope.

Note

--scope and --project work on init, import, apply, status, diff, reconcile, update, verify, and every agent subcommand — anywhere the active config set matters. The global --no-input flag makes any of them fail closed instead of prompting.

Upgrading from the old marker?

The retired single-file .agentsync.toml marker at a repo root is no longer read. agentsync errors and tells you to run agentsync init --scope project and move the settings into the .agentsync/ tree (agents = [...] → an [agents] table; [[mcp]] entries → mcp/<id>.toml files; [plugins] disabled → plugins/<id>.toml with disabled = true; [memory] import is gone — author memory in memory/AGENTS.md).

Scope & the project source tree How discovery and merge work under the hood.