Augment native reference
Start with the Augment setup.
Native mappings
Rules
Rule bodies go into the shared ## Rules block of AGENTS.md. Augment also loads .augment/rules/.
- An always-applied rule already in the block gets no
.augment/rules/file. See target behavior. - A spec with
alwaysApply: falsegetstype: agent_requestedand adescription(falls back to the rule name). Rules have nonamekey. outputs.augment.rules-file: .augment-guidelinesalso writes all rules as one legacy document. It is opt-in, because Augment cuts it first when context runs short.
Entry point off AGENTS.md
Moving the entry point off root AGENTS.md with a file override, or listing it in sync.unmanaged, makes every rule keep a .augment/rules/ file. The default always_apply is left out. Before making the shared file unmanaged, check its effect on other targets.
Agents
Subagents docs. Files go to .augment/agents/<name>.md.
- Frontmatter has
name(required) anddescription(falls back to the spec name). colorandmodelare written when set.coloris written as is. Augment expects an ANSI color name.effortbecomesthinkingwhen it isoff,minimal,low,medium,high, orxhigh. Any other value raises a sync note.x-augment: {thinking: ...}wins overeffort.- Auggie 1.x lists
thinkingin its agent fields. The 0.x agent docs do not, so 0.x may ignore it. - Augment's
toolsanddisabled_toolstake its own tool names, not Claude-style ones. The generictoolsfield uses neither, so it raises a sync note. Setx-augment: {tools: [...]}orx-augment: {disabled_tools: [...]}.
| Field | Accepts |
|---|---|
tools allowlist, Auggie 0.x | view, codebase-retrieval, str-replace-editor, ... |
tools allowlist, Auggie 1.x | Only read, bash, edit, write, grep, find, ls, web-fetch |
disabled_tools | Any tool name |
Skills
Augment also scans .claude/skills/ and .augment/skills/.
Commands
.augment/commands/<scope>/<name>.md. A directory scope from the source folder becomes a nested folder name. description, argument-hint, and model stay in frontmatter.
Ignore
Ignore specs write .augmentignore. import augment restores a hand-written one, keeping pattern order and negation.
MCP
Servers merge into .augment/settings.json under mcpServers. This is the Auggie CLI project file Augment recommends for team-shared servers (config docs), not the IDE Settings Panel.
- Stdio uses
command,args, andenv, with notype. - Remote uses
type: httportype: sse, plusurlandheaders. - Sync changes only its own keys.
shell,startupScript,theme, plugin keys, and tool permissions stay. - If the file is JSONC, sync keeps its keys but drops comments and trailing commas, with a one-line warning.
- Augment documents no per-server
disabledkey.disabled: trueis dropped with a sync note. Useauggie mcp remove. - Transports are
stdio,sse, andhttponly (integrations docs). Atype: wsspec writes no server and raises a sync note.
Hooks
Hooks merge in under hooks, in the same write as mcpServers. Events (hooks docs): PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, PromptSubmit, Notification.
PromptSubmitandNotificationcome from the Auggie 1.x reference. The 0.x reference documents neither as registrable (0.x docs).agnostic-ai hook runtests hooks before a session, using Auggie's event data, shell, and timeout.- A hook on another event, such as Claude Code's
UserPromptSubmit, is skipped with a sync note, andvalidaterejects it. - Auggie's
PromptSubmitpasses the prompt asuser_promptand cannot block, so a shared prompt hook is not renamed. If the hook fits, setx-augment: {event: PromptSubmit}. timeoutis in milliseconds: the spec's seconds times 1000 (vendor default 60000).argsis its own array. Auggie runs the command with them and no shell. Auggie 1.x first expands${VAR}and${VAR:-default}in the command and each argument, sosyncwrites them as you wrote them.- A command without
argsruns as written: 1.x hands it to a shell, 0.x splits it into words or usesbash -cfor shell syntax. matcheris optional onPreToolUseandPostToolUse(default.*). The other five events take none, so sync leaves it out with a note.
Matchers use Augment's tool names:
- Auggie 1.x names its tools
bash,read,edit,write,grep,find,web-fetch, ... and matches case-insensitively. - It still matches the 0.x names
launch-process,view,str-replace-editor, andsave-filefor now. Its/hookscommand flags them (hooks docs). - Auggie 0.x knows only the 0.x names and matches case-sensitively.
- A Claude-style matcher (
Bash,Write, ...) raises a sync note. In 1.x onlyBash,Read,Edit,Write, andGrepreach a tool. In 0.x none does.
Blocking:
- Only
PreToolUsestops a tool: exit 2 orpermissionDecision: "deny". - A
PostToolUsedecision: "block"sends its reason to the agent. The tool has already run. Stopblocks in Auggie 0.x only.- Auggie 1.x runs
Stop,SessionStart,SessionEnd,PromptSubmit, andNotificationhooks in the background, where a block reply does nothing. hook runreports block onPostToolUseandStop, with a note onStop. On the other four it reads a block reply as allow, with a note.
Shared memory
With builtins: [memory], sync adds an executable .augment/hooks/memory-augment-session-start.sh and a SessionStart entry for Auggie CLI on its supported platforms: macOS, Linux, and Windows WSL.
- The script finds the project from its working directory and returns both indexes in
hookSpecificOutput.additionalContext.sync --globalinstalls it too. - Auggie 0.x injects that output.
- Auggie 1.x (stable from 1.2.0) runs
SessionStarthooks in the background and drops their output (1.x hooks docs), so the memory rule tells the agent to read the indexes. - The IDE keeps the memory rule.
- See shared memory for the context limit and the tool's own memory.
Permissions
Settings spec permissions merge into the same file under toolPermissions, which Auggie CLI and Cosmos cloud agents follow. Augment recommends committing .augment/settings.json so the policy applies to every cloud agent in the repo (permissions docs).
- Rules are an ordered array and the first match wins. Deny rules come first, then ask, then allow.
askbecomes{ "type": "ask-user" }. Auggie asks before the call, and denies when there is no interactive UI (headless). Auggie 0.x reads the same type.- Each
permissionis an object such as{ "type": "deny" }. Augment ignores a bare-string permission. - Bare tool names map onto Augment's six tools (
Readtoread,Bashtoterminal,WebFetchtoweb-fetch, ...). - Shell rules use
terminal, the Auggie 0.x name. The 1.x permissions docs call the toolbashand do not listterminalas an old name, but the released 1.2.2 package matchesterminalrules againstbash, so one rule works on both versions. Bash(prefix:*)becomes aterminalrule withshellInputRegex: ^prefix. An exactBash(command)is anchored at both ends.mcp__<server>__<tool>becomes{tool-name}_{server-name}.- Path or URL rules such as
Read(src/**)are not written and raise a sync note. Onlyterminaltakes a matcher, and a barereadwould cover every file. x-augment.toolPermissionswrites Augment's rule objects as is, ahead of the translated ones.- Other
x-augmentkeys, such asshellorstartupScript, merge in as written.
Model and effort:
modelbecomesdefaultModel.effortbecomesdefaultThinkingLevel(off,minimal,low,medium,high, orxhigh). Another value raises a sync note.- Auggie 1.x reads both keys (settings docs). It also reads
modelwhendefaultModelis absent. - Auggie 0.x ignores them and reads only
model. Set it withx-augment: {model: ...}.
Config keys
| Key | Default | Notes |
|---|---|---|
outputs.augment.rules-dir | .augment/rules | |
outputs.augment.agents-dir | .augment/agents | |
outputs.augment.skills-dir | .agents/skills | |
outputs.augment.commands-dir | .augment/commands | |
outputs.augment.ignore-file | .augmentignore | |
outputs.augment.rules-file | unset | opt-in, writes the legacy .augment-guidelines document |
outputs.augment.mcp-file | .augment/settings.json | also the hooks and permissions file, because all three merge into one document |
Import
import augment reads .augmentignore, .augment/agents/*.md, and the toolPermissions policy in .augment/settings.json for Augment's six tools. Nothing else is imported.
- An
ask-userrule goes to theasklist. shellInputRegexentries are skipped (no portable form).- Bare-string
permissionentries are skipped (invalid in Augment). defaultModelbecomesmodel.augment, orx-augment.defaultModelwhen another settings spec sets a different Augment model.defaultThinkingLevelbecomeseffort, following the effort import rules.- In agents,
thinkingbecomeseffortwhen it is one of the six levels. - Agent keys with no portable field (
tools,max_turns, and similar) go underx-augment.