Configuration Reference

The agentsync.toml file is the heart of your agent configuration. It defines the source of truth, how gitignore is managed, and the specific targets for each AI assistant.

By default, agentsync looks for this file at .agents/agentsync.toml.

Global Settings

`source_dir`

The base directory for your source files, relative to the configuration file.

Default: "."

`compress_agents_md`

When enabled, AgentSync creates a compressed copy of AGENTS.md (named AGENTS.compact.md) and points any AGENTS.md targets using type = "symlink" or type = "symlink-contents" to the compressed file. The original AGENTS.md is never modified.

Default: false

compress_agents_md = true

`default_agents`

A list of agent names to run when --agents is not specified on the CLI. Uses case-insensitive substring matching.

Default: [] (empty, meaning all enabled agents will run)

# Only run these agents by default
# When running 'agentsync apply' without --agents, only copilot, claude, and gemini will be processed
default_agents = ["copilot", "claude", "gemini"]

[agents.copilot]
enabled = true

[agents.claude]
enabled = true

[agents.gemini]
enabled = true

[agents.cursor]
enabled = true  # Enabled, but won't run unless explicitly specified with --agents cursor

Behavior:

If default_agents is set and no --agents flag is provided → runs only agents matching default_agents
If --agents flag is provided → uses CLI filter (overrides default_agents)
If default_agents is empty → runs all enabled agents (backward compatible)

Gitignore Management

AgentSync can automatically manage your .gitignore file to ensure that generated symbolic links and agent-specific files are not accidentally committed to version control.

[gitignore].enabled = true remains the default and is the recommended starting point for most teams. Set enabled = false only when your team intentionally wants to commit AgentSync-managed destinations instead of ignoring them. For the maintainer/collaborator workflow, see the Gitignore Team Workflows guide .

[gitignore]
enabled = true
marker = "AI Agent Symlinks"
# Additional entries only - AgentSync automatically adds known patterns for enabled agents
entries = []

enabled: If true, AgentSync will update .gitignore.
marker: The text used in comments to identify the AgentSync section in .gitignore.
entries: A list of additional file paths to add to the ignore list. This is only needed for files not covered by AgentSync’s known patterns.

Behavior notes:

When enabled = true, AgentSync reconciles one marker-delimited managed block in .gitignore.
Managed entries include root-scoped patterns such as /CLAUDE.md when managed destinations live at the repository root.
When enabled = false, agentsync apply removes any matching AgentSync-managed block and preserves unmanaged .gitignore lines before and after it.
That cleanup is marker-aware and idempotent.
agentsync apply --no-gitignore is a command-level opt-out that skips gitignore reconciliation for that invocation only.

If your team wants committed destinations instead of managed ignore rules, use:

[gitignore]
enabled = false

Keep the workflow explanation in the canonical guide ; use this reference section for field semantics.

If you are configuring AgentSync from native Windows and symlink creation fails locally, keep the config unchanged and fix the environment readiness instead. See Windows Symlink Setup .

Known Ignore Patterns

AgentSync automatically adds the following patterns to .gitignore based on which agents are enabled:

Agent	Automatically Added Patterns
claude	`.mcp.json`, `.claude/commands/`, `.claude/skills/`
copilot	`.vscode/mcp.json`
codex	`.codex/config.toml`
gemini	`GEMINI.md`, `.gemini/settings.json`, `.gemini/commands/`, `.gemini/skills/`
cursor	`.cursor/mcp.json`, `.cursor/skills/`
vscode	`.vscode/mcp.json`
opencode	`opencode.json`, `.opencode/command/`, `.opencode/skills/`
windsurf	`.windsurf/mcp_config.json`
cline	`.clinerules`
crush	`CRUSH.md`, `.crush.json`
antigravity	`.agent/rules/`, `.agent/skills/`
amazonq	`.amazonq/rules/`, `.amazonq/mcp.json`
aider	`.aider.conf.yml`, `.aiderignore`
firebase	`.idx/airules.md`, `.idx/mcp.json`
openhands	`.openhands/microagents/`
junie	`.junie/`
augment	`.augment/rules/`
kilocode	`.kilocode/mcp.json`
goose	`.goosehints`
qwen	`.qwen/settings.json`
roo	`.roo/mcp.json`, `.roo/rules/`, `.roo/skills/`
zed	`.zed/settings.json`
trae	`.trae/rules/`
warp	`WARP.md`
kiro	`.kiro/steering/`, `.kiro/settings/mcp.json`
firebender	`firebender.json`
factory	`.factory/mcp.json`, `.factory/skills/`
vibe	`.vibe/config.toml`, `.vibe/skills/`
jetbrains	`.aiassistant/rules/`

Notes:

The entries field in your config is only needed for additional files not covered by the patterns above
All symlink destination paths are also automatically added to .gitignore
Duplicate entries are automatically deduplicated

Agent Definitions

Each assistant is defined under the [agents.<name>] section.

[agents.claude]
enabled = true
description = "Claude Code - Anthropic's AI coding assistant"

[agents.claude.targets.instructions]
source = "AGENTS.md"
destination = "CLAUDE.md"
type = "symlink"

[agents.claude.targets.skills]
source = "skills"
destination = ".claude/skills"
type = "symlink"

[agents.claude.targets.commands]
source = "commands"
destination = ".claude/commands"
type = "symlink-contents"

[agents.claude.targets.monorepo]
type = "nested-glob"
source = "." # Search from project root
pattern = "**/AGENTS.md"
destination = "{relative_path}/CLAUDE.md"
exclude = ["node_modules/**", ".agents/**"]

Skills

Skills targets default to type = "symlink". That keeps the agent-facing skills directory as one directory symlink back to the canonical .agents/skills/ source.

Use symlink for the common case and for repos already using a correct directory symlink such as .claude/skills -> ../.agents/skills.
Use symlink-contents only when the destination must remain a real directory and you want AgentSync to link each child entry individually.
agentsync init --wizard now asks explicitly which mode to use for each migrated skills target, recommends symlink, and preserves an already-correct directory symlink by default.

After the wizard writes config, AgentSync runs a compact validation summary. If you override a skills target to symlink-contents while the destination is already a directory symlink to .agents/skills, the summary warns before your first agentsync apply.

Commands

AgentSync supports a canonical .agents/commands/ directory for agent commands (slash commands, markdown-based prompts, etc.). Commands are synced to agent-specific locations using symlink-contents.

The init command automatically creates .agents/commands/ alongside .agents/skills/. The wizard detects existing command directories (.claude/commands/, .gemini/commands/, .opencode/command/) and offers to migrate them.

Those destinations stay as real directories:

canonical source: .agents/commands/
destination examples: .claude/commands/, .gemini/commands/, .opencode/command/

agentsync status validates those targets as managed directory containers. If .agents/commands/ exists but currently has zero eligible entries, an empty destination directory is still valid and is reported as in sync with 0 managed entries expected.

Agent Compatibility Matrix

AgentSync has two support levels:

Native MCP generation (built-in formatter + merge behavior): claude, copilot, codex, gemini, cursor, vscode, opencode.
Configurable sync targets (rules/skills via symlink): any agent as long as you declare [agents.<name>.targets.*] entries.

The matrix below documents common agent locations and whether AgentSync can handle them today.

Agent	Rules File(s)	MCP Configuration / Notes	Skills Support / Location
AGENTS.md	`AGENTS.md`	Pseudo-agent pattern via `[agents.root]` target	-
GitHub Copilot	`.github/copilot-instructions.md`	`.vscode/mcp.json` (native MCP)	Configurable
Claude Code	`CLAUDE.md`	`.mcp.json` (native MCP)	Configurable; `.claude/skills/`
OpenAI Codex CLI	`AGENTS.md`	`.codex/config.toml` (native MCP)	Configurable; `.codex/skills/`
Pi Coding Agent	-	No native MCP formatter	Configurable
Jules	-	No native MCP formatter	Configurable
Cursor	`.cursor/rules/agentsync.mdc`	`.cursor/mcp.json` (native MCP)	Configurable; `.cursor/skills/`
Windsurf	`.windsurfrules`	No native MCP formatter; `.windsurf/mcp_config.json` ignore	Configurable
Cline	`.clinerules`	No native MCP formatter	Configurable
Crush	`CRUSH.md`	No native MCP formatter; `.crush.json` ignore	Configurable
Amp	`AMPCODE.md`	No native MCP formatter	Configurable
Antigravity	-	No native MCP formatter; `.agent/rules/`, `.agent/skills/` ignores	Configurable
Amazon Q CLI	-	No native MCP formatter; `.amazonq/rules/`, `.amazonq/mcp.json` ignores	Configurable
Aider	-	No native MCP formatter; `.aider.conf.yml`, `.aiderignore` ignores	Configurable
Firebase Studio	-	No native MCP formatter; `.idx/airules.md`, `.idx/mcp.json` ignores	Configurable
Open Hands	-	No native MCP formatter; `.openhands/microagents/` ignore	Configurable

What “configurable” means in practice

Define the rules target under [agents.<name>.targets.<target-id>].
Point source to your canonical file in .agents/ and destination to the tool-specific location.
For non-native MCP agents, manage MCP by symlinking a pre-authored config file as another target.

Target Types

Type	Description
`symlink`	Creates a direct symbolic link from `destination` to `source`.
`symlink-contents`	Creates individual symbolic links for every eligible file inside the `source` directory into the `destination` directory container.
`nested-glob`	Recursively discovers files matching a `pattern` under `source` (relative to project root) and creates a symlink for each at the path produced by expanding the `destination` template.
`module-map`	Maps centrally-managed source files to specific module directories, creating a symlink per mapping with convention-based filenames.

These target types do not change on Windows. If the local Windows environment is not ready to create symlinks, use the Windows Symlink Setup guide rather than changing target semantics.

`symlink-contents` with patterns

When using symlink-contents, you can filter files using a glob pattern:

[agents.claude.targets.commands]
source = "commands"
destination = ".claude/commands"
type = "symlink-contents"
pattern = "*.agent.md"

When this target is empty, agentsync apply leaves .claude/commands/ as a valid empty directory and agentsync status does not treat that container as missing or “not a symlink” just because there are no managed child links yet.

`nested-glob` targets

The nested-glob type is designed for monorepos or projects with nested context files. It walks the source directory (which is relative to the project root, unlike other types) and creates a symlink for every file matching the pattern.

The destination field for nested-glob is a template string that supports the following placeholders:

{relative_path}: The parent directory of the matched file, relative to the search root (e.g., clients/runtime). Files directly in the search root resolve to ..
{file_name}: The full name of the matched file (e.g., AGENTS.md).
{stem}: The filename without its extension (e.g., AGENTS).
{ext}: The file extension without the leading dot (e.g., md).

You can use the exclude field to prune entire subtrees (like node_modules) from the search.

[agents.claude.targets.monorepo]
type = "nested-glob"
source = "packages"
pattern = "**/CONTEXT.md"
destination = "packages/{relative_path}/CLAUDE.md"
exclude = ["**/tests/**", "**/node_modules/**"]

`module-map` targets

The module-map type allows you to define a list of mappings between source files and destination directories. This is useful for distributing different context files to specific modules in a project.

By default, AgentSync uses the agent’s convention filename (e.g., CLAUDE.md for Claude) for the symlink name in each destination. You can override this using filename_override.

[agents.claude.targets.modules]
source = "." # Base directory for source files relative to source_dir
destination = "." # Base directory for destinations relative to project root
type = "module-map"

[[agents.claude.targets.modules.mappings]]
source = "api-context.md"
destination = "src/api"

[[agents.claude.targets.modules.mappings]]
source = "ui-context.md"
destination = "src/ui"
filename_override = "CUSTOM-RULES.md"

In this example:

src/api/CLAUDE.md will point to .agents/api-context.md
src/ui/CUSTOM-RULES.md will point to .agents/ui-context.md

MCP (Model Context Protocol)

Configuration for MCP servers is managed under the [mcp] and [mcp_servers] sections.

For a detailed guide on how to use MCP with AgentSync, see the MCP Integration Guide .