Type to search the docs and updates.

Browse documentation

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.

ValuePersonal 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.

FieldDefaultDescription
agentsagents*.md agent specs.
skillsskills*.md skill specs (or nested <name>/SKILL.md).
rulesrules*.md rule specs.
hookshooks*.yaml hook specs.
mcpsmcps*.yaml MCP server specs.
commandscommands*.md saved prompts.
settingssettings*.yaml permissions and defaults.
reviewsreviews*.md review guidance.
environmentsenvironments*.yaml worktree and sandbox setup.
ignoreignore*.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:

KeyEffect
outputs.<target>.agents: skillWrites agents as on-demand skills on Amp, Crush, Warp, and Zed, which have no subagents (agents as skills).
outputs.<target>.provenance-header: falseDrops 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-pointSays 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 keyValue
A target nameThat target's model id.
defaultThe model id for each target the tier does not name.
effortOne effort for every target, or a per-target map such as {claude: xhigh, codex: high}.
descriptionWhen 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. agnostic-ai explain <spec> shows the model and effort each target gets, and how an alias resolved.

Details: tier rules
  • A model that names no tier stays a literal model id.
  • A tier with only effort keeps each tool's default model.
  • A tier with neither a model nor effort fails to load. A description alone does not make a tier.
  • Any other key that names no target fails with AAI-004, naming the closest target.
  • 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.
  • A tier in agnostic-ai.local.yaml replaces the whole shared tier of the same name, description included.
  • The global home config accepts the key too.
Details: Codex aliases

Claude Code resolves opus, sonnet, haiku, and fable itself. Codex takes only exact ids, so agnostic-ai resolves these aliases when it writes Codex files:

Codex aliasModel id
solgpt-6.1-sol
lunagpt-6-luna
astragpt-6-astra
terragpt-6.1-terra
  • An alias works anywhere Codex reads a model: a tier, model.codex, a shared model, or a settings spec.
  • x-codex.model is written as given.
  • Each release pins the ids. When an upgrade changes one, the next sync prints note: codex: sol now resolves to <new id> (was <old id>) once.
Details: the tier line in instructions files

Sync lists each tier that has a 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.

  • A tier without a description is left out. With no described tier, files do not change.
  • The line goes into each tool's entry-point file after your instructions, Junie's .junie/AGENTS.md, a rules-file that is the tool's entry point, and the managed block sync --global writes.
  • A tool with no root instructions file from sync, such as Cursor, Continue, or Grok in a project, sees the line only in a file another target writes, such as AGENTS.md.
  • import drops the line.
  • The description and the tier name must fit on one line. They cannot hold a backtick, <!--, or -->.
  • Releases before 0.94.0 reject the 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.

ValueBehavior
unsetDefault. A hand-written file becomes one rule with its full body. A file sync wrote splits back into the rules it came from.
trueOne rule spec per ## heading, also for a hand-written file.
falseOne 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.

KeyDefaultEffect
instructions-words2000Words one target loads every session: entry-point file, always-on rule files, and skill and agent descriptions (LINT011).
description-chars1024Characters in one skill or agent description (LINT012). A skill description past 1024 still warns under a higher value.
codex-chain-bytes32768Bytes 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

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.

ValueBehavior
warnDefault. Log to stderr and continue.
errorFail the sync.
silentSkip 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.

TargetKindSet this to write them
geminiskillsoutputs.gemini.emit-skills-as-commands
opencodeskillsoutputs.opencode.emit-skills-as-commands
warpagentsoutputs.warp.workflows-dir
aideragents, skillsoutputs.aider.rules-file
zedhooksoutputs.zed.tasks-file
kiloagents with toolsNone. Use x-kilo: {permission: {...}}.
geminiagents with tools beyond Read/Write/Edit/Bash/Grep/Glob/WebFetch/WebSearchNone. Use x-gemini: {tools: [...]} or drop tools.
crushunknown hook eventsUse one of the 13 native lifecycle events. Matchers require a tool event.
augmenthooks on an event Auggie never fires, such as UserPromptSubmitUse 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.

FieldRequiredDescription
targetyesOne target name, or a list. A name must be a built-in target or listed in targets.
kindyesagents, skills, rules, hooks, mcps, commands, settings, reviews, environments, or ignores.
fieldone of threeMatches "<field> on N specs has no effect on <target>" notes for that field, whatever the reason.
viaone of threeMatches "N specs reach <target> only via <via>" notes, and "only in the source dir (<via>)" notes, with that exact text.
surfaceone of threeMatches "N specs reach <target> but not <surface>" notes with that surface.
reasonyesWhy the note is expected. sync -vv prints it.
  • An accepted note no longer prints on sync, and fail-on-notes ignores it.
  • sync -vv shows it as accepted: with its reason.
  • doctor counts it, and doctor --json reports coverage_accepted.
  • lint warns 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, or surface.
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 sources and outputs paths start at the directory holding agnostic-ai.yaml.
  • Absolute sources paths are used as written.
  • Sync creates output directories as needed and overwrites existing files.
  • A spec or MCP server named .git fails to load.
Details: keeping writes inside the project
  • outputs paths and gitignore.path must 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 outputs path outside the project.
  • gitignore.path must be relative. .git/info/exclude is its one .git/ exception.
  • A sync.unmanaged entry that climbs above the project root fails to load. A leading / anchors an entry at the project root.
  • Sync skips a .agnostic-ai/.sync-state entry 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 .git folder, and names the link.
  • A link that stays inside the project, such as CLAUDE.md linked to AGENTS.md, still works.
  • sync --global follows linked dotfiles as before.
  • A linked .agnostic-ai folder keeps the sync lock and ledger only when it holds AGNOSTIC_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:commit syncs as git/commit.md and git/commit.toml.
  • import qwen and import gemini read a file in a subfolder back as git:commit.
  • Every other target writes a command named git:commit as git-commit (commands). A target that writes another kind's name as one file refuses the write, such as Continue for assistants. sync --check and --dry-run report the same refusal.
  • The next sync removes a colon file an older release wrote.
  • Windows can leave an empty file named git beside it. Gemini CLI sync removes it to make the git folder. For other targets, delete it yourself.
  • Gemini CLI sync stops and names a git file 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, delete git, 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 --global skips 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 sources folders.
  • .agnostic-ai/local/AGNOSTIC_AI.md extends the body on one machine.
  • A model tier with a description adds 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. doctor points 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, and zed.
  • On any other target sync ignores the key and lint warns 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's AGENTS.md does, sync keeps writing that instructions file.
  • Sync then notes that the key has no effect, and lint warns 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.md next to Cline. sync stops with AAI-102 and validate reports 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.

  • validate flags 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.

LayerRootLoaded when
builtinbundled specsenabled with builtins
packs.agnostic-ai/packs/ from agnostic.packs.lockpacks are installed
projectagnostic-ai.yaml sources pathsalways
project-user<project>/.agnostic-ai/localdirectory exists
  • The project-user layer merges into the shared spec field by field (local overrides).
  • Only project uses custom sources paths.
  • $AGNOSTIC_AI_HOME is 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.