agent-layer

MCP server requirements (external tools)

Some MCP servers require a specific runtime or launcher to be installed locally. Agent Layer does not install these dependencies; it only runs the command you configure.

Examples: - Node-based servers often use npx in the command field (requires Node.js + npm). - Python/uv-based servers often use uvx in the command field (requires uv/uvx on your PATH).

If a server fails to start with “No such file or directory,” verify the command exists and is on your PATH, or set command to the full path of the executable.

Install

Install once per machine; choose one:

Interactive setup (optional, `al wizard`)

Run al wizard any time to interactively configure the most important settings:

• Approvals Mode (all, mcp, commands, none, yolo)
• Agent Enablement (Antigravity, Claude, Codex, VS Code, Copilot CLI)
• Model Selection (optional; leave blank to use client defaults, including Codex and Claude reasoning effort where supported)
• MCP Servers & Secrets (toggle default servers; safely write secrets to .agent-layer/.env)
• Warnings (enable/disable warning checks; threshold values use template defaults)

Non-interactive profile mode is also available:

```bash

Quick start

Initialize a repo (run from any subdirectory):

cd /path/to/repo
al init

Then run an agent:

al antigravity

Optional health check:

al doctor

Notes: - al init prompts to run al wizard after seeding files. Use al init --no-wizard to skip; non-interactive shells skip automatically. - al init is intended to be run once per repo. If the repo is already initialized, use al upgrade plan and al upgrade to refresh template-managed files. - By default al init first walks up for an ancestor .agent-layer/, then for an ancestor .git. To install a separate Agent Layer in a subfolder of an existing repo (for example a sub-project that needs its own .agent-layer/), pass al init --here to target the current directory. - al upgrade is the recommended path. For CI-safe non-interactive apply, use al upgrade --yes --apply-managed-updates. Add --apply-memory-updates and/or --apply-deletions only when you explicitly want those categories. - al upgrade automatically creates a managed-file snapshot and rolls changes back if an upgrade step fails. Snapshots are written under .agent-layer/state/upgrade-snapshots/. - Agent Layer does not install clients. Install the target client CLI and ensure it is on your PATH (Antigravity agy, Claude Code CLI, Codex, Copilot CLI, VS Code, etc.).

---

Preview-only diff against current .agent-layer/config.toml

al wizard --profile /path/to/profile.toml

User configuration (gitignored by default, but can be committed)

• .agent-layer/
• config.toml (main configuration; human-editable)
• al.version (repo pin; required)
• instructions/ (numbered *.md fragments; lexicographic order)
• skills/ (workflow markdown; one skill source per command, as <name>/SKILL.md directories)
• commands.allow (approved shell commands; line-based)
• gitignore.block (managed .gitignore block template; customize here)
• .gitignore (ignores repo-local launchers, template copies, and backups inside .agent-layer/)
• .env (tokens/secrets; gitignored)

Repo-local launchers and template copies live under .agent-layer/ and are ignored by .agent-layer/.gitignore.

Configuration (human-editable)

You can edit all configuration files by hand. al wizard updates config.toml (approvals, agents/models, MCP servers, warnings) and .agent-layer/.env (secrets); it does not touch instructions, skills, or commands.allow.

`.agent-layer/config.toml`

Edit this file directly or use al wizard to update it. This is the only structured config file.

Example:

```toml [approvals]

model is optional; when omitted, Agent Layer does not pass a model flag and the client uses its default.

reasoning_effort is optional for Opus models only.

Note: "max" is session-only (passed via --effort CLI flag) and is not written to .claude/settings.json.

Optional agent-specific passthrough config for Claude (arbitrary JSON keys).

Object values are deep-merged into .claude/settings.json; arrays and scalar values are replaced at their key.

model is optional; when omitted, Agent Layer does not pass a model setting and the client uses its default.

reasoning_effort is optional; when omitted, the client uses its default.

Optional agent-specific passthrough config for Codex (arbitrary TOML tables/keys).

These are appended to .codex/config.toml and can override top-level managed keys.

model is optional; when omitted, Agent Layer does not pass a model flag and the client uses its default.

Secrets belong in .agent-layer/.env (never in config.toml).

MCP servers here are the *external tool servers* that get projected into client configs.

http_transport = "sse" # optional: "sse" (default) or "streamable"

url = "https://example.com/mcp" headers = { Authorization = "Bearer ${AL_EXAMPLE_TOKEN}" }

[[mcp.servers]] id = "local-mcp" enabled = false transport = "stdio" command = "my-mcp-server" args = ["--flag", "value"] env = { MY_TOKEN = "${AL_MY_TOKEN}" }

[warnings]

Optional thresholds for warning checks. Omit or comment out to disable.

always prints warnings regardless of this setting.

noise_mode = "default" instruction_token_threshold = 10000 mcp_server_threshold = 15 mcp_tools_total_threshold = 60 mcp_server_tools_threshold = 25 mcp_schema_tokens_total_threshold = 30000 mcp_schema_tokens_server_threshold = 20000

Agent-specific passthrough keys in `agents.codex.agent_specific` or `agents.claude.agent_specific` override Agent Layer-managed keys when they collide. Agent Layer emits a warning on every sync if you override managed keys. Codex project trust is managed automatically for the current absolute repo root.

#### Built-in placeholders

Agent Layer provides a built-in `${AL_REPO_ROOT}` placeholder for file paths in MCP server configs.
It expands to the absolute repo root during `al sync` and `al doctor`, and it does **not** need to be in `.env`.
Paths that start with `${AL_REPO_ROOT}` or `~` are expanded and normalized; other relative paths are passed through as-is.

Example:

Default MCP server client exclusions

Some default MCP servers exclude VS Code via the clients field:

• ripgrep and filesystem: Excluded from VS Code because VS Code/Copilot Chat has native file search and access capabilities. Adding these servers would duplicate functionality and increase context window usage.

You can override these exclusions by editing clients in your config.toml.

HTTP transport (http_transport)

For HTTP MCP servers, http_transport controls how al doctor connects:

• sse (default)
• streamable

Omit http_transport to default to sse.

Warning thresholds ([warnings])

Warning thresholds are optional. When a threshold is omitted, its warning is disabled. Values must be positive integers (zero/negative are rejected by config validation). al sync uses instruction_token_threshold and, when version_update_on_sync = true, warns if a newer Agent Layer release is available. al doctor evaluates all configured MCP warning thresholds.

Set version_update_on_sync = true to opt in to update warnings during al sync and al <client>; omit it or set it to false to keep update warnings limited to al init, al doctor, and al wizard. Set noise_mode = "default" to keep all warnings (recommended), noise_mode = "reduce" to hide only suppressible non-critical warnings, or noise_mode = "quiet" to suppress agent-layer informational output. Errors still print, client output is unaffected, and al doctor always prints warnings regardless of noise mode.

Use al <client> --quiet (or -q) for one-off quiet runs; the flag always wins over config.

Approvals modes (approvals.mode)

These modes control whether the agent is allowed to run shell commands and/or MCP tools without prompting. Edit them to match your team's preferences; al wizard can update approvals.mode.

• all: auto-approve both shell commands and MCP tool calls (where supported)
• mcp: auto-approve only MCP tool calls; shell commands still require approval (or are restricted)
• commands: auto-approve only shell commands; MCP tool calls still require approval
• none: approve nothing automatically
• yolo: skip all permission prompts where the client supports it (sends --dangerously-skip-permissions to Claude, approval_policy=never + sandbox_mode=danger-full-access + web_search=live to Codex, --yolo to Copilot CLI, chat.tools.global.autoApprove to VS Code); intended for sandboxed/ephemeral environments

Client notes: - Some clients do not support all approval types; Agent Layer generates the closest supported behavior per client.

Codex may still deny or override these settings if its requirements.toml disallows them.

Secrets: `.agent-layer/.env`

API tokens and other secrets live in .agent-layer/.env (always gitignored).

Important: Only environment variables that start with the AL_ prefix are sourced from .env (others are ignored). This convention avoids conflicts with your shell environment and ensures Agent Layer's variables don't override existing environment variables when VS Code terminals inherit the process environment.

Example keys: - AL_CONTEXT7_API_KEY - AL_TAVILY_API_KEY - AL_GITHUB_PERSONAL_ACCESS_TOKEN (only when using the optional GitHub MCP server)

Your existing process environment takes precedence. .agent-layer/.env fills missing keys only, and empty values in .agent-layer/.env are ignored (so template entries cannot override real tokens). This behavior is consistent whether launching via al commands or repo-local launchers like open-vscode.app, open-vscode.sh, or open-vscode.command.

reasoning_effort is not currently supported for Copilot CLI in Agent Layer.

[mcp]

CLI overview

Common usage:

al antigravity
al claude
al codex
al copilot
al vscode

Why do MCP servers fail to start in VS Code on macOS?

If MCP servers that use npx are failing in VS Code, your GUI environment may not see a user-directory Node install. Install Node via Homebrew (brew install node) so VS Code can find node and npx, and avoid per-user installs that only exist in shell profiles.

Why did some VS Code settings disappear after `al sync`?

Some VS Code extensions (for example Peacock) write settings through the VS Code configuration API in a way that can land inside the Agent Layer-managed block in .vscode/settings.json.

If that happens, Agent Layer will replace that managed block on the next al sync, and those extension-written settings will be removed.

Fix: 1. Manually edit .vscode/settings.json and move extension-owned settings outside the managed marker block (// >>> agent-layer to // <<< agent-layer). 2. If the managed block is currently the last block in the file, add a user-owned tail anchor key after it:

{
  // >>> agent-layer
  // ... Agent Layer managed settings ...
  // <<< agent-layer
  "__settingsTailAnchor": 0
}

This keeps a stable non-managed tail position for extension writes.

---

VS Code (Codex + Claude extensions)

al vscode is the single command for launching VS Code with both Codex and Claude extension support. It is enabled when either [agents.vscode] or [agents.claude_vscode] is set to enabled = true in config.toml.

• When [agents.vscode] is enabled, CODEX_HOME is set for the Codex extension.
• When [agents.claude_vscode] is enabled, Claude files (.mcp.json, .claude/settings.json) are generated. YOLO mode sets claudeCode.allowDangerouslySkipPermissions in .vscode/settings.json.
• When [agents.claude] local_config_dir = true is set, al claude sets CLAUDE_CONFIG_DIR for per-repo settings and caches isolation. For al vscode, CLAUDE_CONFIG_DIR is set only when both local_config_dir = true and [agents.claude_vscode] is enabled; otherwise al vscode clears only stale repo-local values and preserves user-defined non-repo values. This is opt-in; when disabled (the default), Claude uses your global ~/.claude/ configuration. For al claude only, a user-set CLAUDE_CONFIG_DIR pointing outside the repo is preserved even when local_config_dir is disabled. Note: auth credentials are stored globally in Claude Code's OS credential store (macOS Keychain service "Claude Code-credentials"; Linux libsecret/gnome-keyring) regardless of this setting (upstream limitation).
• VS Code settings are generated when either agent is enabled.
• Supports --no-sync to skip sync before opening VS Code.

The Codex VS Code extension reads CODEX_HOME and the Claude extension reads CLAUDE_CONFIG_DIR from the VS Code process environment at startup.

Agent Layer provides repo-specific launchers in .agent-layer/ that set CODEX_HOME (and CLAUDE_CONFIG_DIR when both local_config_dir and agents.claude_vscode are enabled) correctly for this repo:

Launchers: - macOS: open-vscode.app (recommended; VS Code in /Applications or ~/Applications) or open-vscode.command (uses code CLI) - Linux: open-vscode.desktop or open-vscode.sh (uses code CLI; shows a dialog if missing)

These launchers invoke al vscode, so the al CLI must be available on your PATH. al vscode also runs launch preflight checks and fails fast with guidance when code is missing on PATH or .vscode/settings.json has a managed-block marker conflict.

If you use the CLI-based launchers, install the code command from inside VS Code: - macOS: Cmd+Shift+P -> "Shell Command: Install 'code' command in PATH" - Linux: Ctrl+Shift+P -> "Shell Command: Install 'code' command in PATH"

Note: Codex authentication is per repo because each repo uses its own CODEX_HOME. When you open VS Code with a different repo, you will need to reauthenticate with Codex. If local_config_dir = true is enabled under [agents.claude], Claude settings and caches are isolated per repo (via CLAUDE_CONFIG_DIR). Known upstream limitation: Claude Code currently stores auth credentials in the OS credential store (macOS Keychain service "Claude Code-credentials"; Linux libsecret/gnome-keyring) regardless of CLAUDE_CONFIG_DIR, so authentication is always shared globally until this is fixed upstream.

For contributor-level implementation details, see docs/architecture/vscode-launch.md.

---

FAQ

Disable Claude Code's structured clarification-question tool for this project.

agent_specific.permissions.deny = ["AskUserQuestion"]