Configuration reference
The keys you change most are in Configuration. This page holds the rest, in full.
memory
memory.personal sets where the memory built-in keeps personal memory. It is one user's choice, so set it in agnostic-ai.local.yaml; in agnostic-ai.yaml it fails as AAI-004.
| Value | Personal memory folder |
|---|---|
checkout (default) | .agnostic-ai/local/memory/ in each checkout. |
repo | ~/.agnostic-ai/local/memory/<repository name>-<hash>/, one folder that every worktree of the repository shares (under $AGNOSTIC_AI_HOME when set). |
# agnostic-ai.local.yaml
memory:
personal: repo
In a Git project with managed ignores, init --memory writes memory.personal: repo to a new agnostic-ai.local.yaml.
See one store per repository for what sync writes and which tools can save there.
sources
Sync skips missing directories. Paths follow the path rules. A source root can be a directory symlink (macOS, Linux) or junction (Windows); sync does not follow links below it.
| Field | Default | Description |
|---|---|---|
agents | agents | *.md agent specs. |
skills | skills | *.md skill specs (or nested <name>/SKILL.md). |
rules | rules | *.md rule specs. |
hooks | hooks | *.yaml hook specs. |
mcps | mcps | *.yaml MCP server specs. |
commands | commands | *.md saved prompts. |
settings | settings | *.yaml permissions and defaults. |
reviews | reviews | *.md review guidance. |
environments | environments | *.yaml worktree and sandbox setup. |
ignore | ignore | *.md context exclusion patterns. |
outputs
outputs.<target>.* overrides where one target writes. An unknown field fails with AAI-004. Each target page lists its keys and defaults, starting at the targets index. Claude Code and Codex also accept settings blocks.
outputs:
claude:
rules-dir: .claude/rules
cursor:
mcp-file: .cursor/mcp.json
Special keys:
| Key | Effect |
|---|---|
outputs.<target>.agents: skill | Writes agents as on-demand skills on Amp, Crush, Warp, and Zed, which have no subagents (agents as skills). |
outputs.<target>.provenance-header: false | Drops the Generated by agnostic-ai line from that target's files. A shared root file such as AGENTS.md drops it only when every target that reads it sets the key. |
outputs.trae.rules-mode: entry-point | Says Trae's Include AGENTS.md in the context switch is on, so Trae loads each always-on rule from AGENTS.md once (Trae). |
nested-glob-rules, exec-policies-from-permissions (Codex) | Change how rules and permissions are written (Codex config keys). |
models
Name each model role (a tier) once, then use the name in specs instead of a vendor's model id.
models:
frontier: {claude: fable, codex: astra, effort: xhigh, description: "for ambitious, open-ended work"}
strong: {claude: opus, codex: sol, effort: high, description: "for everyday coding"}
balanced: {claude: sonnet, codex: terra, effort: medium, description: "when strong breezes through the task"}
fast: {claude: haiku, codex: luna, effort: low, description: "for lookups and high-volume subagents"}
An agent with model: fast gets haiku (Haiku 5.5 today) in Claude Code and gpt-6-luna in Codex, both at low effort. Other targets keep their default model. Skills, commands, and settings specs name tiers the same way. To pin a Claude version, write the exact id, such as claude: claude-haiku-5-5.
| Tier key | Value |
|---|---|
| A target name | That target's model id. |
default | The model id for each target the tier does not name. |
effort | One effort for every target, or a per-target map such as {claude: xhigh, codex: high}. |
description | When to use the tier, in one line. Write the joining word yourself, such as for or when. |
Per-spec overrides and which value wins: model tiers. Claude Code resolves Sync lists each tier that has a agnostic-ai explain <spec> shows the model and effort each target gets, and how an alias resolved.Details: tier rules
model that names no tier stays a literal model id.effort keeps each tool's default model.effort fails to load. A description alone does not make a tier.lint warns when a spec names a tier with no entry and no default for a target that writes the spec.lint warns with LINT025 when a tier is named like a Claude model.lint warns with LINT026 when a tier's default is a Claude model another target cannot load.agnostic-ai.local.yaml replaces the whole shared tier of the same name, description included.Details: Codex aliases
opus, sonnet, haiku, and fable itself. Codex takes only exact ids, so agnostic-ai resolves these aliases when it writes Codex files:Codex alias Model id solgpt-6.1-sollunagpt-6-lunaastragpt-6-astraterragpt-6.1-terramodel: a tier, model.codex, a shared model, or a settings spec.x-codex.model is written as given.sync prints note: codex: sol now resolves to <new id> (was <old id>) once.Details: the tier line in instructions files
description on one line in the instructions every tool loads, sorted by tier name. The example above gives:Model tiers: `balanced` when strong breezes through the task; `fast` for lookups and high-volume subagents; `frontier` for ambitious, open-ended work; `strong` for everyday coding.description is left out. With no described tier, files do not change..junie/AGENTS.md, a rules-file that is the tool's entry point, and the managed block sync --global writes.AGENTS.md.import drops the line.<!--, or -->.description key as an unknown target.
import
import.codex.shred
Sets how agnostic-ai import codex treats a nested AGENTS.md. The root file always imports into .agnostic-ai/AGNOSTIC_AI.md.
| Value | Behavior |
|---|---|
| unset | Default. A hand-written file becomes one rule with its full body. A file sync wrote splits back into the rules it came from. |
true | One rule spec per ## heading, also for a hand-written file. |
false | One rule spec per AGENTS.md, with the full body as written. |
import:
codex:
shred: false
lint
Set limits on text loaded in every session. agnostic-ai lint warns when a limit is exceeded; lint --strict exits 1.
| Key | Default | Effect |
|---|---|---|
instructions-words | 2000 | Words one target loads every session: entry-point file, always-on rule files, and skill and agent descriptions (LINT011). |
description-chars | 1024 | Characters in one skill or agent description (LINT012). A skill description past 1024 still warns under a higher value. |
codex-chain-bytes | 32768 | Bytes of AGENTS.md Codex reads for one directory: the root file plus each scoped file down to it, review sections included (LINT011). |
lint:
instructions-words: 3000
description-chars: 500
codex-chain-bytes: 24576
- A missing key or
0keeps the default. A negative value fails as AAI-004. - The defaults follow vendor limits: Claude Code's 200 lines for
CLAUDE.md, and the Agent Skills specification for descriptions. - Whatever the word budget, lint also warns past Codex's 32 KiB
AGENTS.mdcap and Antigravity's 24,000-byte rule cap. - The global home config accepts the key too.
- See
lint.
doctor
doctor.check-references.ignore
Link destinations doctor --check-references never reports as broken.
doctor:
check-references:
ignore:
- url # exact destination, as written in the source Markdown
- gcp-url
- "*-placeholder" # glob; `*` stays inside one path segment
An entry is the destination text as written, such as url for [Logs](url), or a path.Match glob, as in sync.unmanaged.
on-unsupported
Applies when a tool does not support a spec kind, such as hooks for Jules or project-level mcps for Cline.
| Value | Behavior |
|---|---|
warn | Default. Log to stderr and continue. |
error | Fail the sync. |
silent | Skip without logging. |
Any other value fails with AAI-004.
It also covers imported Claude hook root references that cannot be translated. See project-root paths.
Coverage notes
sync prints a note: line when a tool does not write specs of a kind you have, because it needs an opt-in key or has no files for them:
note: 1 agent reaches warp only via outputs.warp.workflows-dir
Setting the named key clears the note. sync -vv shows every note.
| Target | Kind | Set this to write them |
|---|---|---|
gemini | skills | outputs.gemini.emit-skills-as-commands |
opencode | skills | outputs.opencode.emit-skills-as-commands |
warp | agents | outputs.warp.workflows-dir |
aider | agents, skills | outputs.aider.rules-file |
zed | hooks | outputs.zed.tasks-file |
kilo | agents with tools | None. Use x-kilo: {permission: {...}}. |
gemini | agents with tools beyond Read/Write/Edit/Bash/Grep/Glob/WebFetch/WebSearch | None. Use x-gemini: {tools: [...]} or drop tools. |
crush | unknown hook events | Use one of the 13 native lifecycle events. Matchers require a tool event. |
augment | hooks on an event Auggie never fires, such as UserPromptSubmit | Use one of its seven events, or x-augment: {event: PromptSubmit}. |
coverage
These keys accept coverage notes or make them fail sync. on-unsupported: error never fails on a note. Both keys are project-only: sync --global warns about a coverage: key in the home config and ignores it.
coverage:
fail-on-notes: true
accept:
- target: codex
kind: agents
field: tools
reason: Codex limits come from sandbox_mode; tools stays portable for other targets.
- target: [codex, gemini, cursor]
kind: skills
field: argument-hint
reason: Only Claude Code shows the hint.
coverage.fail-on-notes
Default false. When true, every form of sync fails on each coverage note that names a target and is not accepted. That includes --dry-run, --watch, --json, --check, and --plan.
- Sync prints the notes, even under
-q. - Sync rolls back the writes.
coverage.accept
List each note the project accepts and the reason. Each entry names one note with exactly one of field, via, or surface.
| Field | Required | Description |
|---|---|---|
target | yes | One target name, or a list. A name must be a built-in target or listed in targets. |
kind | yes | agents, skills, rules, hooks, mcps, commands, settings, reviews, environments, or ignores. |
field | one of three | Matches "<field> on N specs has no effect on <target>" notes for that field, whatever the reason. |
via | one of three | Matches "N specs reach <target> only via <via>" notes, and "only in the source dir (<via>)" notes, with that exact text. |
surface | one of three | Matches "N specs reach <target> but not <surface>" notes with that surface. |
reason | yes | Why the note is expected. sync -vv prints it. |
- An accepted note no longer prints on
sync, andfail-on-notesignores it. sync -vvshows it asaccepted:with its reason.doctorcounts it, anddoctor --jsonreportscoverage_accepted.lintwarns with LINT024 when an entry matches no note on one of its targets.- Config loading fails on an unknown target, a repeated entry, or an entry with no
field,via, orsurface.
What coverage.accept cannot match
Notes that start with a target name, such as note: codex: outputs.codex.config.notify is not written, cover the whole setup. coverage.accept cannot match them, and fail-on-notes ignores them. A failure from on-unsupported: error, such as a Claude model name on another target, is not a note either.
Watched inputs
sync --watch runs again when the config, sources, local specs, or overlays change. See watch mode for the full list. Overlays in .agnostic-ai/overlays/ hold keys that specs do not cover, such as Claude statusLine or Codex [history].
Path semantics
- Relative
sourcesandoutputspaths start at the directory holdingagnostic-ai.yaml. - Absolute
sourcespaths are used as written. - Sync creates output directories as needed and overwrites existing files.
- A spec or MCP server named
.gitfails to load.
Details: keeping writes inside the project
outputspaths andgitignore.pathmust stay inside the project and out of.git/, so a cloned repository cannot make sync write elsewhere.- The config fails to load when one of them climbs above the project root or points into
.git/. - Sync stops before writing to an absolute
outputspath outside the project. gitignore.pathmust be relative..git/info/excludeis its one.git/exception.- A
sync.unmanagedentry that climbs above the project root fails to load. A leading/anchors an entry at the project root. - Sync skips a
.agnostic-ai/.sync-stateentry outside the project or inside.git/, names it in a warning, and never removes or changes that file. - Project sync refuses to write or remove through a link that leads outside the project or into a
.gitfolder, and names the link. - A link that stays inside the project, such as
CLAUDE.mdlinked toAGENTS.md, still works. sync --globalfollows linked dotfiles as before.- A linked
.agnostic-aifolder keeps the sync lock and ledger only when it holdsAGNOSTIC_AI.md. - A source root can be a directory symlink (macOS, Linux) or junction (Windows). Sync does not follow links below it.
Details: Windows file names with a colon
- Windows stores a file whose name holds a colon as a hidden stream of the file named before the colon. So sync refuses to write such a file on Windows.
- Qwen Code and Gemini CLI turn each colon in a command name into a folder. A command named
git:commitsyncs asgit/commit.mdandgit/commit.toml. import qwenandimport geminiread a file in a subfolder back asgit:commit.- Every other target writes a command named
git:commitasgit-commit(commands). A target that writes another kind's name as one file refuses the write, such as Continue for assistants.sync --checkand--dry-runreport the same refusal. - The next sync removes a colon file an older release wrote.
- Windows can leave an empty file named
gitbeside it. Gemini CLI sync removes it to make thegitfolder. For other targets, delete it yourself. - Gemini CLI sync stops and names a
gitfile that holds content when no colon output in the last sync explains it, or when you edited its old colon file. Copy any text you need, deletegit, and sync again. - On Windows, import refuses an MCP server or other spec whose file name would hold a colon, such as a server named
ns:tool, and names the file. import --globalskips such a server with a warning that names the home config file.- Rename the server before you import it. Continue needs the rename too, since sync writes
.continue/mcpServers/<name>.yaml. - An older release reported such an import as done and may have left an empty file such as
.agnostic-ai/mcps/ns. Delete it.
Entry-point files
sync copies .agnostic-ai/AGNOSTIC_AI.md into one root entry-point file per enabled tool (per-target table).
- Put the instructions every tool shares in this file. Every session loads it, so keep it to what an agent cannot infer from the code.
- Rules, agents, and skills stay in their own
sourcesfolders. .agnostic-ai/local/AGNOSTIC_AI.mdextends the body on one machine.- A model tier with a
descriptionadds one line after the body. - Sync never overwrites
AGNOSTIC_AI.md. It overwrites only the root entry points. - If the file is missing, sync creates it with one line saying the tool files are generated from
.agnostic-ai/. - An earlier release may have left the old long default text.
doctorpoints it out. Replace it with your own instructions.
Details: legacy merged rules file
outputs.<target>.rules-file: <path> restores the legacy layout. The adapter writes one merged document at <path>, including the built-in skill instructions.
- Two adapters writing different content to one path fail unless you set
sync.collision-policy: prefer-spec. - When
<path>is the target's own entry-point file (outputs.claude.rules-file: CLAUDE.md), sync skips the pointer body. - Any other path keeps the entry-point file. For
claude, the pointer body also gains an@<path>import. - These targets write it:
aider,amp,antigravity,augment,claude,codex,copilot,gemini,goose,kimi,opencode,pi,qwen,vibe,warp, andzed. - On any other target sync ignores the key and
lintwarns with LINT062. The target keeps its entry-point file and rules as if the key were unset.
When <path> is also the instructions file sync writes for another enabled target, sync writes that instructions file there instead of the merged one. The merged file holds neither the AGNOSTIC_AI.md body nor the other target's rules, so it never wins.
- If the target still reads that file (as its own entry point, or through Claude's
@<path>import) and the other target's version carries all its rules, as Amp'sAGENTS.mddoes, sync keeps writing that instructions file. - Sync then notes that the key has no effect, and
lintwarns with LINT063. - A run of that target alone, such as
sync --target codex, writes the same file. - Otherwise the rules are lost, as with
outputs.codex.rules-file: AGENTS.mdnext to Cline.syncstops with AAI-102 andvalidatereports it.
Per-target paragraphs
.agnostic-ai/AGNOSTIC_AI.md accepts the ::target, ::targets, and ::end fences from spec bodies, with the same rules for shared entry-point files.
validateflags a fence that names an unknown target or one that reads no entry-point file.- import explains how a fenced source is read back.
Layered specs
Specs load from four layers, lowest first. A higher layer overrides a spec with the same kind and name. A new name adds a spec. agnostic-ai list shows each spec's layer.
| Layer | Root | Loaded when |
|---|---|---|
builtin | bundled specs | enabled with builtins |
| packs | .agnostic-ai/packs/ from agnostic.packs.lock | packs are installed |
project | agnostic-ai.yaml sources paths | always |
project-user | <project>/.agnostic-ai/local | directory exists |
- The
project-userlayer merges into the shared spec field by field (local overrides). - Only
projectuses customsourcespaths. $AGNOSTIC_AI_HOMEis not a project layer.
Global configuration
agnostic-ai sync --global installs your own instructions, skills, hooks, settings, agents, and MCP servers for every project. It reads ~/.agnostic-ai/, not the current project's specs. Global configuration covers the source layout, target selection, ownership, and recovery.
agnostic-ai sync --global --only claude,codex --dry-run
agnostic-ai sync --global --only claude,codex
agnostic-ai sync --global --only claude,codex --check
Shared names
A home skill can hide a project skill with the same name. See shared names.
Default model and effort
Home settings specs set user defaults. See user settings.
MCP servers
See user MCP servers.