Reference

This page is the authoritative reference for configuration, environment variables, and the al CLI. It is written for the moments when you want certainty: configuring a repo, debugging a launch, or reviewing what al will change.

If you are setting up Agent Layer for the first time, start with Getting started. For upgrade policy commitments (event model, guarantees, migration rules, and platform matrix), use Upgrades.

Agent Layer is explicit by design. It prefers failing fast over guessing, and it treats generated files as disposable outputs rather than hand-maintained sources. When you need to know exactly what will change on disk, this is the contract.

In this page

• Configuration
• Environment variables
• CLI guide

Configuration

.agent-layer/config.toml is the primary structured configuration file. It is the single source of truth for approvals, agents, MCP servers, and warning thresholds. If you treat one file as the contract, make it this one—everything else is derived from it.

al wizard updates config.toml and .agent-layer/.env. Everything else is edited by hand.

Most repos only need a few deliberate choices: pick an approvals mode, enable the agents you actually use, and add MCP servers one at a time. The file is validated on every run, so mistakes surface immediately instead of becoming “mystery behavior” later.

caution

Never put secrets in config.toml. Secrets belong in .agent-layer/.env.

Example

[approvals]
# one of: "all", "mcp", "commands", "none", "yolo"
mode = "all"

[agents.gemini]
enabled = true
# model is optional; when omitted, the client uses its default.
# model = "..."
# reasoning_effort is not currently supported for Gemini in Agent Layer.

[agents.claude]
enabled = true
# model = "..."
# reasoning_effort is optional for Opus models only.
# reasoning_effort = "medium" # low | medium | high
# local_config_dir isolates Claude Code settings and caches per repo.
# When true, al claude sets CLAUDE_CONFIG_DIR=<repo>/.claude-config.
# For al vscode, CLAUDE_CONFIG_DIR is set only when both local_config_dir
# and agents.claude_vscode are enabled. Otherwise, al vscode clears only
# stale repo-local values and preserves user-defined non-repo values.
# Note: auth is stored globally by Claude Code in the OS credential store
# (macOS Keychain service "Claude Code-credentials"; Linux libsecret/gnome-keyring)
# regardless of this setting (upstream limitation).
# local_config_dir = false
# Optional agent-specific passthrough config for Claude (arbitrary JSON keys).
# These are shallow-merged at the top level into .claude/settings.json.
# Nested objects are replaced (not deep-merged).
# [agents.claude.agent_specific]

[agents.claude_vscode]
enabled = true

[agents.codex]
enabled = true
# model is optional; when omitted, Agent Layer does not pass a model setting and the client uses its default.
# model = "gpt-5.3-codex"
# reasoning_effort is optional; when omitted, the client uses its default.
# reasoning_effort = "xhigh" # codex only
# 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.
# [agents.codex.agent_specific]
# [agents.codex.agent_specific.features]
# multi_agent = true
# prevent_idle_sleep = true

[agents.vscode]
enabled = true

[agents.antigravity]
enabled = true

[mcp]
# MCP servers are external tool servers projected into client configs.

[[mcp.servers]]
id = "filesystem"
enabled = false
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem@2026.1.14", "${AL_REPO_ROOT}"]

[warnings]
# Optional thresholds for warning checks. Omit or comment out to disable.
# Warn when a newer Agent Layer version is available during sync runs.
version_update_on_sync = true
# Warning output noise control: "default" keeps all warnings, "reduce" hides suppressible non-critical warnings,
# and "quiet" suppresses agent-layer informational output (warnings still print in `al doctor`).
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.

Sections at a glance

Section	Purpose
[approvals]	auto-approval policy for commands and MCP tools
[agents.*]	enablement and model selection per client
[[mcp.servers]]	external MCP server definitions
[warnings]	optional thresholds for token and server limits, plus sync update warnings

Approvals

[approvals] controls auto-approval behavior.

Agents

Each agent has an enabled flag and optional model value. Claude supports reasoning_effort (low, medium, high) for Opus models; Codex supports reasoning_effort with its own set of options. Omit reasoning_effort (and model) to use the client defaults. Claude also supports local_config_dir (boolean, default false); when true, al claude sets CLAUDE_CONFIG_DIR to a repo-local directory for per-repo settings and caches isolation. Note: auth credentials are stored globally by Claude Code in the OS credential store (macOS Keychain service "Claude Code-credentials"; Linux libsecret/gnome-keyring) regardless of this setting (upstream limitation). For al vscode, CLAUDE_CONFIG_DIR is set only when both local_config_dir is true and agents.claude_vscode is enabled; otherwise al vscode clears only stale repo-local values and preserves user-defined non-repo values.

Supported agents:

• gemini
• claude
• claude_vscode
• codex
• vscode
• antigravity

MCP servers

Each [[mcp.servers]] entry must include:

• id
• enabled
• transport (http or stdio)

Optional fields:

• clients to restrict which clients receive a server (valid values: gemini, claude, vscode, codex, antigravity; note that claude_vscode uses the claude client)
• http_transport (sse or streamable) for HTTP servers
• headers for HTTP auth and metadata
• command, args, env for stdio servers

Secrets, placeholders, and client projection

Agent Layer is designed to keep secrets out of your canonical config and out of any files you might commit:

• Put secrets in .agent-layer/.env (only AL_-prefixed variables are loaded).
• Reference secrets in config.toml using placeholders like ${AL_GITHUB_TOKEN}.
• Let al sync project those placeholders into each client's supported format.

Agent Layer never writes resolved secret values back into config.toml. Generated client outputs are treated as build artifacts, and some clients require concrete values in their own config formats. When that happens, those outputs are gitignored by default.

Here is how placeholder projection works for MCP servers:

Client	Placeholder syntax in generated config
Claude Code (.mcp.json)	${AL_TOKEN}
Gemini (.gemini/settings.json)	${AL_TOKEN}
VS Code (.vscode/mcp.json)	${env:AL_TOKEN}
Codex (.codex/config.toml)	headers become env-var references; URLs/commands/args/env values are resolved because Codex does not support placeholders

Practical guidance:

• Prefer secrets in headers (headers = { Authorization = "Bearer ${AL_TOKEN}" }) over secrets in URLs.
• For maximum portability, keep non-Authorization secret headers as exact placeholders (for example "X-Api-Key" = "${AL_API_KEY}"), not mixed into longer strings.
• Some services use API keys in URLs (for example the seeded Tavily template). In that case, remember clients like Codex may require a fully resolved URL and will write it only into gitignored outputs.

HTTP example

[[mcp.servers]]
id = "example-api"
enabled = true
transport = "http"
url = "https://example.com/mcp"
headers = { Authorization = "Bearer ${AL_EXAMPLE_TOKEN}" }

Stdio example

[[mcp.servers]]
id = "ripgrep"
enabled = true
transport = "stdio"
command = "npx"
args = ["-y", "mcp-ripgrep@0.4.0"]

Warnings

Warning thresholds are optional. When a threshold is omitted, its warning is disabled. All values must be positive integers.

Warnings are used by:

• al sync for instruction token thresholds (and optional update warnings)
• al doctor for MCP server and schema thresholds

Warning output now includes source and severity labels so operators can distinguish internal/config issues from network or external-dependency issues.

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 to control warning verbosity:

• default: keep all warnings (recommended)
• reduce: hide only suppressible non-critical warnings
• quiet: suppress agent-layer informational output (warnings still print in al doctor)

Validation rules

Agent Layer validates config.toml on every run. Common validation rules:

• approvals.mode must be one of all, mcp, commands, none, yolo
• enabled flags must be set for all agents and MCP servers
• MCP transport must be http or stdio
• http_transport (when set) must be sse or streamable
• HTTP servers cannot set command or args
• Stdio servers cannot set url or headers

Environment variables

Agent Layer uses a small set of environment variables for versioning and offline behavior. It also loads secrets from .agent-layer/.env.

This surface area is intentionally small. Configuration should live in the repo where it can be reviewed, while environment variables act as escape hatches for CI, offline work, and temporary overrides.

Versioning and cache

Variable	Purpose
AL_VERSION	force a version (overrides the repo pin)
AL_NO_NETWORK	disable update checks and downloads
AL_CACHE_DIR	override the pinned-version cache directory

These variables only affect version dispatch, update checks, and downloads. They do not disable MCP server networking.

For supported upgrade paths and release-line compatibility guarantees, see Upgrades.

Known issue in v0.6.0 and earlier

In versions 0.6.0 and earlier, the internal AL_SHIM_ACTIVE environment variable can leak into VS Code's integrated terminal when launching via al vscode. This causes subsequent al commands in that terminal to fail with:

version dispatch already active (current X.Y.Z, requested A.B.C)

Workaround: Clear the AL_SHIM_ACTIVE environment variable in the affected terminal before running al commands:

• bash/zsh: unset AL_SHIM_ACTIVE

This issue is fixed in v0.6.1 and later, where AL_SHIM_ACTIVE is automatically stripped from child process environments.

Secrets from .agent-layer/.env

Only variables prefixed with AL_ are loaded from .agent-layer/.env.

Rules:

• Your existing process environment takes precedence
• Empty values in .env are ignored
• .env is always gitignored

Example:

AL_CONTEXT7_API_KEY=your-key-here
AL_TAVILY_API_KEY=your-key-here
# Optional: only when using a GitHub MCP server
AL_GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here

Built-in placeholder

${AL_REPO_ROOT} is a built-in placeholder for the absolute repo root. Use it in MCP server command arguments or paths when you want runtime expansion.

Example:

[[mcp.servers]]
id = "filesystem"
enabled = true
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem@2026.1.14", "${AL_REPO_ROOT}"]

CLI guide

The al CLI syncs repo-local configuration and launches your chosen client. This section focuses on behavior, safety, and the files each command touches. Use it as a runbook when you want to know exactly what a command will change. For exact flags, run al --help or al <command> --help.

The command surface is intentionally small. Most of the time you only need one rhythm: al init once, al <client> every day, al doctor when something feels off.

Command map

Command	Purpose
al init	Initialize a repo with Agent Layer templates and memory files.
al upgrade	Apply template-managed updates and update the repo pin (interactive by default; non-interactive requires --yes plus one or more apply flags; line-level diff previews shown by default, configurable with --diff-lines).
al upgrade plan	Show a dry-run, plain-language categorized upgrade plan with line-level diff previews (configurable with --diff-lines).
al upgrade prefetch	Download and cache a release binary ahead of time (use --version X.Y.Z explicitly on dev builds).
al upgrade rollback --list	List available upgrade snapshot IDs and statuses before rollback.
al upgrade rollback <snapshot-id>	Restore an applied upgrade snapshot by ID (snapshot IDs are JSON filename stems under .agent-layer/state/upgrade-snapshots/).
al upgrade repair-gitignore-block	Restore .agent-layer/gitignore.block from templates and reapply the root .gitignore managed block.
al wizard	Interactive configuration plus profile mode (--profile) and backup cleanup (--cleanup-backups).
al sync	Regenerate client configs without launching a client.
al <client>	Sync and launch a client (gemini/claude/codex/vscode/antigravity).
al doctor	Validate configuration and probe enabled MCP servers.
al completion	Print or install shell completions (bash/zsh/fish).
al --version	Print the installed Agent Layer version.
al help	Show help for any command.

Init

al init sets up Agent Layer in a repository.

If .agent-layer/ already exists, al init errors; use al upgrade plan and al upgrade instead.

It is scaffolding: it creates the files that make behavior explicit and repeatable, so day-to-day work becomes “edit the source of truth, regenerate outputs,” not “hunt for the right config format.”

What it does

• Creates .agent-layer/ (configuration, instructions, approvals, MCP servers)
• Creates docs/agent-layer/ (project memory files)
• Installs a managed .gitignore block

Steps (high level)

1. Creates required directories.
2. Writes template-managed files under .agent-layer/ and docs/agent-layer/ (seeds user-owned files only when missing).
3. Adds or updates the managed .gitignore block.
4. If running interactively, prompts to run the wizard unless --no-wizard is set.

Files and directories it touches

Typical .agent-layer/ files include:

• config.toml (seeded if missing; user-owned), commands.allow, instructions/, skills/
• al.version (repo pin; required)
• .env (seeded if missing; user-owned secrets, always gitignored)
• .gitignore (internal ignores) and gitignore.block (root .gitignore template)
• .agent-layer/state/managed-baseline.json (managed ownership baseline state; gitignored)

Gitignore template

.agent-layer/gitignore.block is the template file. It must contain only ignore patterns and comments (no managed markers and no template hash). Agent Layer copies it verbatim and injects the managed header and template hash only when updating the root .gitignore. If the template file contains managed markers or a hash line, al sync will error; run al upgrade to restore the template file.

Typical project memory files under docs/agent-layer/:

• ISSUES.md, BACKLOG.md, ROADMAP.md, DECISIONS.md, COMMANDS.md, CONTEXT.md

Wizard prompt

By default, al init prompts to run the setup wizard after seeding files. Use --no-wizard to skip it. In non-interactive environments, the wizard is skipped.

Version pinning and network

• If you are running a release build, al init writes .agent-layer/al.version.
• You can set the initial pin explicitly with --version X.Y.Z (or --version latest).
• .agent-layer/al.version is required for supported usage. If it is missing or invalid, run al upgrade to repair it.
• Pin file parsing ignores blank lines and # comments, and expects exactly one version line.
• If the pin file is empty, invalid, or contains multiple version lines, dispatch warns and falls back to the current CLI version; run al upgrade to rewrite a valid pin.
• Update checks and pinned downloads require network access unless AL_NO_NETWORK=1 is set.
• For upgrade contract details and release-versioned migration notes, see Upgrades.

Upgrade

al upgrade applies template-managed updates in an existing repo.

What it does

• Updates .agent-layer/al.version to match the currently running al binary
• Prompts before overwriting managed template files unless apply flags are explicitly selected
• Shows line-level diff previews before overwrite decisions by default
• In the default interactive flow, prompts about unknown files under .agent-layer/ and docs/agent-layer/ and only deletes them if you explicitly approve
• In non-interactive or explicit-category apply (e.g., --yes --apply-managed-updates), requires the separate --apply-deletions flag before unknown files are eligible for deletion
• Never overwrites .agent-layer/config.toml or .agent-layer/.env
• Creates an automatic snapshot for managed upgrade targets and auto-rolls back if an upgrade step fails
• Stores snapshots under .agent-layer/state/upgrade-snapshots/
• Supports snapshot discovery and manual restore via al upgrade rollback --list and al upgrade rollback <snapshot-id>

Use --diff-lines N to raise the per-file diff preview cap (default: 40 lines). For a concise team/CI runbook, see Upgrade checklist.

Upgrade rollback

al upgrade rollback <snapshot-id> restores a previously applied managed-file snapshot.

• al upgrade rollback --list shows available snapshot IDs and statuses
• Snapshot IDs are the .json filename stems in .agent-layer/state/upgrade-snapshots/
• Only snapshots in applied status are rollback-eligible
• Rollback fails loudly when a snapshot is missing, malformed, or non-rollbackable

Upgrade prefetch

al upgrade prefetch downloads and verifies a release binary into the local Agent Layer cache without applying template updates.

• Use it to pre-warm CI runners or offline environments.
• In release builds, it defaults to the currently running al version.
• In dev builds, pass --version X.Y.Z explicitly.

Repair gitignore block

al upgrade repair-gitignore-block restores .agent-layer/gitignore.block to the embedded template and reapplies the root .gitignore managed block.

Use this when .agent-layer/gitignore.block is invalid (for example it accidentally includes managed markers or template-hash lines).

Upgrade plan

al upgrade plan is a read-only upgrade preview. It does not write files.

It compares your repository state against templates embedded in the currently running al binary (not an older repo-pinned binary).

Use it before al upgrade to understand what would change:

• Template additions
• Template updates
• Template renames (heuristic, confidence-annotated)
• Template removals/orphans
• Config key migrations (when migration manifests are present)
• Pin version change (current -> target)
• Readiness checks (for example unresolved placeholders, process-env vs .env collisions, ignored empty .env assignments, path-expansion anomalies, stale VS Code --no-sync outputs, floating dependency specs, and stale disabled-agent artifacts)

al upgrade plan also includes line-level diff previews for changed files. Use --diff-lines N to raise the per-file diff preview cap (default: 40 lines).

Each diff preview still carries internal ownership metadata (upstream template delta, local customization, mixed upstream and local, unknown no baseline) used by upgrade decision logic, but al upgrade plan text output intentionally hides ownership diagnostics.

al upgrade plan supports plain-language text output only.

Wizard

al wizard guides you through approvals, enabled agents, model selection, MCP servers, and warning thresholds.

Use it when you want to get to a safe, working configuration quickly, or when you would rather answer questions than hand-edit TOML.

What it edits

• .agent-layer/config.toml
• .agent-layer/.env

The wizard rewrites config.toml in a deterministic preferred section order and creates backups (.bak) before modifying .agent-layer/config.toml or .agent-layer/.env. Inline comments on modified lines may be moved to leading comments or removed; the original formatting is preserved in the backup files.

Additional modes:

• al wizard --profile /path/to/profile.toml: preview-only profile rewrite diff
• al wizard --profile /path/to/profile.toml --yes: apply profile and run sync
• al wizard --cleanup-backups: delete .agent-layer/config.toml.bak and .agent-layer/.env.bak

Navigation

• Arrow keys: Navigate options
• Space / x: Toggle selection (multi-select steps)
• Enter: Confirm and continue
• Esc: Go back to the previous step (on the first step, prompts to exit)
• Ctrl+C: Exit immediately without saving changes

Secret prompt controls:

• skip: disable the current default MCP server for this run
• cancel: exit without applying changes

It is safe to re-run when you want to revisit settings.

Sync

al sync regenerates client configs from .agent-layer/ without launching a client.

Think of sync as a build step. You can run it any time you want to refresh generated outputs without starting a client.

What it does

• Validates .agent-layer/config.toml
• Reads .agent-layer/instructions/, .agent-layer/skills/, .agent-layer/commands.allow, and .agent-layer/.env
• Regenerates client outputs and launchers

Steps (high level)

1. Load and validate config.toml, then resolve secrets from .agent-layer/.env.
2. Parse instructions and skills to build client-specific outputs.
3. Write generated configs and launchers for enabled clients.
4. Emit warnings if any thresholds in [warnings] are exceeded.

Skill format

Skill sources align with the agentskills.io specification, with explicit backward-compatibility behavior documented below.

.agent-layer/skills/ uses directory format:

• .agent-layer/skills/<name>/SKILL.md (canonical; lowercase skill.md is accepted as a compatibility fallback)

Frontmatter fields:

• Required: name, description
• Optional: license, compatibility, metadata, allowed-tools

Validation notes (al doctor):

• Name checks are NFKC-normalized and normalization-aware when matching name to the canonical source name.
• Name limits: max 64 Unicode characters, lowercase letters/digits/hyphens only, no leading/trailing/consecutive hyphens.
• Description limit: max 1024 Unicode characters.
• Compatibility limit (when present): max 500 Unicode characters.
• Size recommendation: al doctor warns when a skill source exceeds 500 lines.
• Missing name remains load-compatible (name is derived from path), but al doctor warns.
• Missing or empty description fails load/sync (fail-loud).
• Directory skills using lowercase skill.md load for compatibility, but al doctor warns to use canonical SKILL.md.

Example:

---
name: code-audit
description: Run a code quality audit.
---
# Your command body here

Generated outputs

Common outputs include:

• .agent/skills/
• .gemini/settings.json, .claude/settings.json, .mcp.json
• .codex/ (generated config, rules, and skills)
• .vscode/mcp.json, .vscode/prompts/, and a managed block in .vscode/settings.json
• .github/copilot-instructions.md
• AGENTS.md, CLAUDE.md, GEMINI.md
• repo-local VS Code launchers under .agent-layer/ when VS Code is enabled (for example open-vscode.command, open-vscode.sh, and open-vscode.app/)

These files are derived outputs and safe to delete. Running al sync will recreate them.

Warnings

al sync evaluates instruction token thresholds from [warnings] and emits warnings if they are exceeded. If version_update_on_sync = true, it also checks for a newer Agent Layer release.

Launch a client

al <client> syncs before launch by default. Supported clients:

• al gemini
• al claude
• al codex
• al vscode
• al antigravity

These commands read .agent-layer/, regenerate client outputs, and then launch the selected client.

This is the default workflow for day-to-day use: you get a clean regenerate and a launch in one command, which keeps behavior consistent even when you switch tools.

al <client> forwards any extra arguments to the underlying client. If you need to use Agent Layer flags as well, place -- before the client arguments. --no-sync is supported by al vscode and must appear before --. For an explicit false value, use --no-sync=false (space-separated values like --no-sync false are not supported and will be passed through).

al vscode preflight now fails fast with clear guidance when:

• code is missing on PATH
• .vscode/settings.json has a malformed managed block marker state

Examples:

al claude -- --help
al vscode --no-sync -- --reuse-window

Doctor

al doctor validates configuration, checks for missing secrets, and probes enabled MCP servers.

Use it as your early warning system. It is the fastest way to answer “is my config valid,” “are my secrets present,” and “are my tools reachable.”

What it does

• Validates .agent-layer/config.toml
• Reports missing AL_ secrets referenced by your config
• Connects to each enabled MCP server and lists tools
• Evaluates MCP warning thresholds from [warnings]
• Checks for newer releases and warns if you are behind

Steps (high level)

1. Validate configuration and resolve secrets from .agent-layer/.env.
2. Probe each enabled MCP server and collect tool metadata.
3. Compute warning thresholds and report any overages.
4. Check for release updates (unless networking is disabled).

Timeouts and network

• al doctor waits up to 30 seconds per enabled MCP server before timing out.
• It uses network access for MCP servers and update checks. Set AL_NO_NETWORK=1 to disable update checks and pinned downloads.

Completion

al completion prints shell completion scripts to stdout or installs them in the standard user location.

al completion zsh
al completion zsh --install

Supported shells: bash, zsh, fish.

Help and version

al --help
al help <command>
al --version

Use these to confirm available commands, flags, and the installed version.