Claude Code native reference

Start with the Claude Code setup. This page covers native mappings and overrides. For shared home configuration and ownership, see global configuration.

Rules and instruction loading

Claude Code reads .claude/rules/**/*.md natively. Sync translates globs or paths into paths: frontmatter and removes portable activation keys. A comma-separated string produces one pattern per entry.

A directory scope and file patterns add together: scope: src/a with globs: tests/a/** covers both directories. Omit scope for a file-only filter, and keep the source outside a folder that implies scope.

CLAUDE.md carries the shared instructions. When another target writes an identical root AGENTS.md, Claude's file imports it with @AGENTS.md, plus Claude-only text. Sync keeps a full copy if a rules appendix or target-specific text would make the files differ. If the existing Claude file already imports AGENTS.md, sync can keep that layout without another target.

A session started in a subfolder treats the root @AGENTS.md as an outside import. Interactive sessions ask once; non-interactive claude -p skips it. Use explain to inspect planned files, then confirm native loading in that working directory.

Legacy rules-mode: import is for versions without native rules loading. rules-file: CLAUDE.md joins rule bodies there; another rules-file path gets an import from CLAUDE.md.

Agents, skills, and commands

A declared disallowedTools or x-claude.disallowedTools wins over readonly. A null override omits it. Claude Code skips names starting with - or containing :; sync rejects them before writing, including names from x-claude.

For global agents and user settings, see global configuration.

Hook mappings

Hooks merge into .claude/settings.json. See the native hook reference for event names and payloads, and portable hooks for shared events.

Handlers keep timeout, statusMessage, if, and once. args, async, asyncRewake, and shell are command-only. once has no effect in settings hooks; Claude Code honors it only in skill frontmatter. Experimental agent handlers are not emitted.

failClosed: true becomes onFailure: "block" for command and HTTP handlers. Use synchronous PreToolUse or UserPromptSubmit when a failed check must stop an action. Claude ignores it for Stop, SubagentStop, TaskCompleted, TeammateIdle, or async command handlers. Import retains other native onFailure values under x-claude; portable failClosed: true wins.

With command hooks, sync sets AGNOSTIC_AI_TARGET: claude in settings env; an explicit settings value wins. When Cursor is also selected, a portable hook's Claude copy exits under Cursor to avoid running twice. Other compatibility reads need cross-target checks.

MCP mappings

.mcp.json is rebuilt from MCP specs on every sync. Import hand-written servers before syncing.

alwaysLoad and bareElicitationCapability preserve explicit true and false; x-claude overrides them. They are Claude-only fields. See the MCP reference for their native behavior.

Remote OAuth keeps clientId, callbackPort, authServerMetadataUrl, and space-separated scopes. Sync never writes oauth.clientSecret; Claude Code keeps it in the system keychain.

disabled: true writes disabledMcpjsonServers in project settings. It requires the project .mcp.json path; a custom path fails. Sync records only its generated rejections in .claude/.agnostic-ai-mcp-disabled.json and removes the entry when re-enabled.

Environment mappings

dev-commands become .claude/launch.json preview servers: command splits into runtimeExecutable and runtimeArgs, auto-port becomes autoPort, and cwd stays project-relative. x-claude.autoVerify sets autoVerify. Import normalizes ${workspaceFolder} paths; a URL-only configuration stays native with a note.

setup becomes .claude/hooks/agnostic-ai-worktree-setup.sh. Session, subagent, and EnterWorktree hooks run it once per new linked worktree, using Bash. Windows needs Git Bash. x-claude.setup: false omits them. Other environment fields have no Claude output and get a note. See worktree setup.

Config keys

import claude and agnostic-ai doctor read the resolved paths, so a moved directory still imports and syncs back unchanged.

dir moves the whole tool directory: with dir: vendor/.claude, rules land in vendor/.claude/rules/, commands in vendor/.claude/commands/, and {{rules_dir}} and other path variables resolve there. Per-kind keys override their own path. The next full sync removes old files as orphans. Claude Code auto-loads only a project-root .claude/rules/, so a moved rules directory needs rules-mode: import.

With gitignore.enabled, the managed .gitignore block also lists /.claude/agent-memory-local/, /.claude/settings.local.json, /.claude/worktrees/, and /.claude/scheduled_tasks.lock, following outputs.claude.dir. It omits .claude/agent-memory/ (memory: project), which is shareable. Ignoring does not untrack: run git rm -r --cached .claude/agent-memory-local if that store is committed.

The block also goes into .worktreeinclude, so new worktrees start with the ignored outputs (gitignore). gitignore.ignore-worktree-include: true ignores the managed .worktreeinclude too; gitignore.worktree-include: false leaves it to you.

Agent memory

A top-level memory key gives a subagent a directory that persists across sessions. Claude Code acts on it; support in other tools differs. See agent memory fields.

---
name: code-reviewer
description: Reviews diffs for bugs and style.
memory: project
---

Claude Code creates the directory on first use. Session auto memory (~/.claude/projects/<project>/memory/) is separate. Sync leaves it alone unless the memory built-in points it at the shared personal store. That needs auto memory on: with autoMemoryEnabled off or CLAUDE_CODE_DISABLE_AUTO_MEMORY set, Claude saves nothing there. See Memory and local state.

Claude settings

sync --global --only claude maps a home settings spec's permissions.default-mode to permissions.defaultMode in ~/.claude/settings.json. It merges the home's allow, ask, and deny rules into the lists there. import --global claude copies user-level rules into the home. See global settings and rule ownership.

outputs.claude.settings declares .claude/settings.json keys directly. Layers, lowest first (a later layer wins):

1. Captured overlay (from import claude).
2. Agnostic settings specs (.agnostic-ai/settings/), the cross-tool source for permissions, model, and effort. effort lands as effortLevel when it is low, medium, high, or xhigh.
3. This outputs.claude.settings block.
4. The hooks block built from your hook specs.
5. An x-claude block on a settings spec.

Unset keys fall through to the layer below. x-claude merges: x-claude.permissions.deny adds to the translated deny list, and only single values such as model are replaced.

Without a captured overlay, sync merges permission lists into the on-disk settings.json and records the rules it added in .claude/.agnostic-ai-permissions.json. The next sync removes those first, so a rule dropped from a spec, or moved from allow to deny, leaves the file. Hand-written and overlay rules stay. The first sync without a record keeps every rule and records the spec ones.

outputs:
  claude:
    settings:
      attribution:
        commit: ""
        pr: ""

Other settings survive import and sync through the overlay agnostic-ai import claude captures (.agnostic-ai/overlays/claude.settings.json). For a single value in both, this block wins. permissions allow/deny/ask lists combine across the overlay, settings specs, and this block.

Import

agnostic-ai import claude reads the Claude Code files:

Instructions. A hand-written CLAUDE.md imports whole, not split into rules, since each section would then load twice. When .claude/rules/ exists (even empty), rule files come only from it. Import follows Claude Code's lookup order: CLAUDE.md, .claude/CLAUDE.md, AGENTS.md, .claude/AGENTS.md. Only one importer may slice the root AGENTS.md, so import skips it when codex, amp, warp, crush, kiro, or opencode imports too. Delete .claude/CLAUDE.md after the next sync, as import says, or Claude Code loads both it and the root file.

Nested CLAUDE.md. Sync writes nested rules to .claude/rules/<dir>/, so import tells you to delete each nested CLAUDE.md it read. doctor --fix deletes one still matching its rule and keeps one you edited. Once .claude/rules/ holds a directory's scoped rules, sync itself deletes a nested CLAUDE.md that only imports @AGENTS.md. Any other line, or a sync.unmanaged entry, keeps the file. sync --backup keeps the deleted file as CLAUDE.md.bak; revert restores it.

Agents, skills, commands. allowed-tools moves under x-claude:, where lint accepts it and sync writes it back. An agent model naming a Claude model (an alias such as opus or fable, inherit, or a claude-* id) imports as model: {claude: <name>}, so other targets use their default; sync writes model: <name> back.

Settings. Permission lists become a portable settings spec that lint checks and every target gets (with a sync note where unsupported). Import skips rules that another settings spec or outputs.claude.settings.permissions declares. Add target: claude to keep them Claude-only. The overlay captures every other non-hooks key, including permissions.defaultMode. Re-import after editing settings.json by hand.

effortLevel is the one key import moves out of the overlay. A valid value becomes effort in <settings>/claude.yaml, which every target syncs, unless another settings spec sets a different effort; then it goes under x-claude.effortLevel. An invalid value stays in the overlay.

For enforcement boundaries, see protected paths in Claude Code.