Amp settings.json settings

The JSON Schema URL used by your editor for validation, descriptions, and completions in settings files.

string, e.g. https://ampcode.com/cli-settings.schema.json

Glob patterns for paths always included in fuzzy file search even if ignored by Git, useful for build output or generated files referenced with @ mentions.

array of strings, default []

Shows cost information for threads in the CLI while working. Workspace admins can also hide costs for all members.

boolean, default true

Adds the Amp-Thread-ID: <thread-url> trailer to agent Git commits. While disabled, Amp refuses to run a git commit whose message writes the trailer by hand.

boolean, default true

Adds the Co-authored-by: Amp <amp@ampcode.com> trailer to agent Git commits. Never added in remote orbs whose project Git identity is Amp.

boolean, default true

Customizes CLI keybindings. Configuring a command replaces its default; use an array to keep the old shortcut, or null to unbind. User keymap entries override workspace entries.

object mapping command IDs to string | string[] | null, default {}

Keymap command ID shown in the amp.keymap example; bound to Ctrl+S by default per the keybindings page.

string | string[] | null

Keymap command ID shown in the amp.keymap example for copying the thread URL.

string | string[] | null

Keymap command ID shown in the amp.keymap example for interrupting the agent (default Esc Esc).

string | string[] | null

Keymap entry that changes the <leader> key (default Ctrl+X).

string

Local (stdio) MCP server field: the command to run. Required for stdio servers in amp.mcpServers and skill mcp.json.

string

Local MCP server field: the command arguments.

string[] (optional)

Local MCP server field: environment variables for the server.

object of strings (optional)

Remote MCP server field: the server endpoint. Required for HTTP servers.

string

Remote MCP server field: HTTP headers sent with requests. Can contain ${amp:id-token} for HTTPS servers in orbs.

object of strings (optional)

HTTP MCP server field in the settings JSON Schema selecting the transport.

http | sse | http-first

HTTP MCP server field in the settings JSON Schema for OAuth client configuration.

object: clientId (required), clientSecret, authUrl (required), tokenUrl (required), scopes (string[]), redirectUrl

Common field for MCP servers defined in skills: tool names or glob patterns that choose which tools are exposed. Optional but recommended.

string[]

Header placeholder that makes Amp send an Amp ID token to an HTTPS MCP server in an orb. Works only in headers of HTTPS servers without OAuth; outside an orb the server fails to connect.

Defines default thread visibility per repository origin.

object mapping origin to private | workspace | group

Plays notification sounds when the agent completes a task or is blocked waiting for input. Over SSH, or when AMP_FORCE_BEL is set, Amp sends a terminal bell instead.

boolean, default true

Lets ampcode.com create new threads that open in the interactive TUI on this machine, in the directory where it was started.

boolean, default false

Lets amp --no-tui runners install CLI updates and restart into them once no thread is running, at most once every 12 hours, keeping their flags.

boolean, default true

Lets amp --no-tui runners inject ampcode.com Secrets & Env Vars into threads' shell commands, MCP servers, and plugins. Same as --amp-env.

boolean, default false

Disables loading skills from Claude Code directories (.claude/skills/, ~/.claude/skills/, ~/.claude/plugins/cache/).

boolean, default false

Disables loading skills from ~/.config/agents/skills/ and ~/.agents/skills/.

boolean, default false

Additional directories containing skills, colon-separated (semicolon on Windows). ~ expands to home; relative paths resolve against the workspace root.

string

Copies transcript selections to the clipboard automatically. When false, press Ctrl+C to copy a selection.

boolean, default true

Expands thinking and tool call details by default in the CLI transcript.

boolean, default false

Automatically archives the active thread and connected background threads when quitting Amp.

boolean, default false

Disables specific tools by name. Use builtin:toolname to disable only the built-in tool; * globs are supported.

array of strings, default []

Allows or blocks MCP servers that match a pattern; the first matching rule applies and unmatched servers are allowed. Match remote servers by url and local servers by command and args.

array of {matches: object, action: allow | reject}, default []

Controls update checking: warn shows notifications, disabled turns checks off (also disables runner auto-update), auto installs updates. AMP_SKIP_UPDATE_CHECK=1 overrides it.

"auto" | "warn" | "disabled", default "auto"

Managed-settings field giving the date used to determine which backward-compatibility migrations Amp must apply. Supported in managed-settings.json and the workspace document.

string, YYYY-MM-DD

Setting named as not allowed in the workspace managed settings document because it could make the client unable to reach the server that provides the settings.

Setting named as not allowed in the workspace managed settings document because it could make the client unable to reach the settings server.

Setting that is local to one machine and therefore cannot be set in the workspace managed settings document.

Setting that is local to one machine and therefore cannot be set in the workspace managed settings document.

Skill name in SKILL.md YAML frontmatter. Amp uses the first skill with a given name; in hosted repositories it must match the directory name.

string

Skill description the model sees and uses to decide when to load the skill.

string

Defines MCP servers for a skill. If both mcpServers and a sibling mcp.json exist, Amp uses mcpServers.

object of MCP server definitions

In a plugin-bundled skill, lists the plugin's own tools so they stay hidden from the model until the skill is loaded.

list of tool names

YAML front matter in an @-mentioned guidance file so it is included only after Amp reads a matching file. Globs are implicitly prefixed with **/ unless they start with ../ or ./.

string[]

.amp/services.yaml field: required shell command run through a login shell. A service with a portal must listen on $PORT.

string

.amp/services.yaml field: working directory relative to the repository root.

string, default repository root

.amp/services.yaml field: fixed local port. Omit to let Amp choose a free port that stays the same across restarts.

integer 1 to 65535

.amp/services.yaml field: string environment variables for the command; values can refer to another service's public URL. PORT, PUBLIC_URL, and AMP_THREAD_ID cannot be set.

object of strings

.amp/services.yaml field: HTTP path Amp requests after the port opens; 2xx and 3xx mean ready.

path string

.amp/services.yaml field: primary portal link. true means / with the service name; or a mapping with url, title, description.

true | {url, title, description}

.amp/services.yaml field: more portal links for the same service; each needs url and title, and folders can group links.

list

.amp/services.yaml field: whether Amp injects the portal review widget.

boolean, default true

.amp/services.yaml field: optional nonempty list of platforms the service runs on; omit to run on all platforms.

[linux] | [darwin] | [linux, darwin]