Amp CLI reference - Config files
Amp config files and locations
Amp documents 23 config files, including ~/.config/amp/settings.json, .amp/settings.json and managed-settings.json. These are the files and directories Amp reads its configuration from. Each row gives the docs' description, accepted values and an example where one is documented.
Last verified 8 official pagesFull Amp reference
| Path | Description | Example |
|---|---|---|
~/.config/amp/settings.json | User settings file on macOS and Linux (or settings.jsonc). On Windows: %USERPROFILE%\.config\amp\settings.json or settings.jsonc. Docs: ~/.config/amp/settings.json | -no example |
.amp/settings.json | Workspace settings (or .amp/settings.jsonc), found by searching upward from the current directory to the repository root. Overrides user settings, except for keymaps; MCP servers here need approval. Docs: .amp/settings.json | -no example |
managed-settings.json | Admin-deployed managed settings file. Paths: macOS /Library/Application Support/ampcode/managed-settings.json, Linux /etc/ampcode/managed-settings.json, Windows %ProgramData%\ampcode\managed-settings.json. Takes precedence over the workspace managed document. Docs: managed-settings.json | -no example |
https://ampcode.com/cli-settings.schema.json | JSON Schema for Amp CLI user and workspace settings files. Docs: https://ampcode.com/cli-settings.schema.json | -no example |
$HOME/.config/amp/AGENTS.md | Personal guidance file, always included if it exists; $HOME/.config/AGENTS.md is also supported. Docs: $HOME/.config/amp/AGENTS.md | -no example |
/etc/ampcode/AGENTS.md | System-wide or organization-managed guidance, always included. Also /Library/Application Support/ampcode/AGENTS.md (macOS) and %ProgramData%\ampcode\AGENTS.md (Windows). Docs: /etc/ampcode/AGENTS.md | -no example |
.amp/plugins/ | Project plugins directory at the project root; .ts or .js files or <plugin-name>/index.ts directories. Highest precedence among plugin sources. Docs: .amp/plugins/ | -no example |
~/.config/amp/plugins/ | System plugins directory on macOS and Linux ($XDG_CONFIG_HOME/amp/plugins/ if set; %USERPROFILE%\.config\amp\plugins\ on Windows). Applies to your projects on that machine. Docs: ~/.config/amp/plugins/ | -no example |
~/.config/agents/skills/ | First skill source in precedence; machine-local skills, and the install target of | -no example |
~/.agents/skills/ | Second skill source in precedence (global agent-agnostic directory). Docs: ~/.agents/skills/ | -no example |
~/.config/amp/skills/ | Third skill source in precedence (Amp user skills directory). Docs: ~/.config/amp/skills/ | -no example |
.agents/skills/ | Project skills in the project and searched parent directories; can be committed with the project. Docs: .agents/skills/ | -no example |
.claude/skills/ | Claude-compatible skill locations: .claude/skills/, ~/.claude/skills/, and ~/.claude/plugins/cache/. Skipped when amp.skills.disableClaudeCodeSkills is set. Docs: .claude/skills/ | -no example |
SKILL.md | Skill definition file with YAML frontmatter inside a skill directory. Local directories are searched up to five levels below each skills root. Docs: SKILL.md | ---
name: my-skill
description: A description of what this skill does
---
# My Skill Instructions |
mcp.json | Sibling file in a skill directory defining MCP servers whose tools stay hidden until the skill loads. Docs: mcp.json | {
"linear": {
"url": "https://mcp.linear.app/sse",
"includeTools": ["list_issues", "create_issue", "update_issue"]
}
} |
.agents/setup | Executable script at the repository root that prepares new project orbs and their snapshots. Stopped after 20 minutes; log at /home/user/.cache/amp/logs/setup.log. Docs: .agents/setup | chmod +x .agents/setup
git add .agents/setup |
.agents/resume | Executable script run after orb activation and each wake for quick authentication or repair. Amp waits up to 10 seconds; log at /home/user/.cache/amp/logs/resume.log. Docs: .agents/resume | chmod +x .agents/resume
git add .agents/resume |
.amp/services.yaml | Declares long-running orb services and their portal links; needs a nonempty top-level services mapping. Docs: .amp/services.yaml | services:
web:
command: pnpm dev -- --host 0.0.0.0 --port "$PORT"
health: /healthz
portal: true |
.amp/portals/*.json | Generated portal link manifests for the current orb and thread; ignore in Git. Custom manifests can be written by hand. Docs: .amp/portals/*.json | .amp/portals/ |
/home/user/.cache/amp/logs/ | Orb hook logs: setup.log for .agents/setup and resume.log for .agents/resume, replaced each run. Docs: /home/user/.cache/amp/logs/ | -no example |
/run/amp/workload-identity-request-token | Workload identity request credential available during pre-clone, pre-setup, and .agents/setup scripts; removed after setup. Docs: /run/amp/workload-identity-request-token | -no example |
~/.amp/bin/amp-desktop-helper/<version> | Install location of Amp Desktop Helper.app on macOS runners using --desktop. Docs: ~/.amp/bin/amp-desktop-helper/<version> | -no example |
~/.cache/amp/runner-desktop/<runner-id> | Per-runner compositor, logs, and sockets for Linux runner desktops. Waymote is downloaded to ~/.amp/bin/waymote/<waymote-version> on x64 Linux. Docs: ~/.cache/amp/runner-desktop/<runner-id> | -no example |
The rest of the Amp reference
FAQ
How many config files does Amp have?
The official Amp docs list 23 config files, including ~/.config/amp/settings.json, .amp/settings.json and managed-settings.json. All of them are in the table above, in the docs' order.
What does ~/.config/amp/settings.json do in Amp?
User settings file on macOS and Linux (or settings.jsonc). On Windows: %USERPROFILE%\.config\amp\settings.json or settings.jsonc.
Where are Amp config files documented?
On 8 official docs pages at ampcode.com, last read on October 17, 2026. Every row in the table links the exact section it came from.
Sources
Last verified . Names and examples are copied verbatim from the 8 official pages below, and every row above links the exact section it came from.
- ampcode.com/docs/cli/settings4 items
- ampcode.com/docs/customize/agents-md2 items
- ampcode.com/docs/customize/plugins2 items
- ampcode.com/docs/customize/skills7 items
- ampcode.com/docs/orbs/customizing3 items
- ampcode.com/docs/orbs/portals2 items
- ampcode.com/docs/orbs/handling-secrets1 item
- ampcode.com/docs/cli/runners2 items
Newsletter
Know when your tools change
One email per week. New coding agent releases, the flags and commands they add, and what they mean for how you work.