Agent Layer

One repo-local source of truth for instructions, skills, MCP servers, and approvals across coding agents.

Agent Layer keeps AI-assisted development consistent across tools by generating each client’s required config from a single .agent-layer/ folder. Install al once per machine, run al init per repo, then run al <client> (e.g., al claude) to sync and launch.

Key properties:

• Local-first, no telemetry
• Deterministic outputs from canonical inputs
• Explicit approvals and command allowlists
• Per-repo credential isolation (Codex logins per repository; Claude settings and caches isolation with auth pending upstream fix)

Comparison:

Manual per-client setup	Agent Layer
duplicate instructions across multiple formats	one canonical source under .agent-layer/
inconsistent approvals and command policies	consistent approvals and allowlists
MCP servers added in one client and forgotten in another	generated MCP config for every supported client
shared global credentials across repos	per-repo credential isolation for Codex; per-repo settings and caches isolation for Claude
no single place to review or audit changes	audit in version control

If Agent Layer improves your workflow, please consider starring the repository. Stars help new users discover the project.

---

Supported clients

MCP = Model Context Protocol (tool/data servers).

Client	Instructions	Skills	MCP servers	Approved commands
Gemini CLI	✅	✅	✅	✅
Claude Code CLI	✅	✅	✅	✅
Claude Code VS Code Extension	✅	✅	✅	✅
VS Code / Copilot Chat	✅	✅	✅	✅
Codex CLI	✅	✅	✅	✅
Codex VS Code extension	✅	✅	✅	✅
Copilot CLI	✅	✅	✅	✅
Antigravity	✅	✅	❌	❌

Notes:

• Codex, Gemini, VS Code/Copilot, Copilot CLI, and Antigravity consume shared skills from .agents/skills/<name>/SKILL.md.
• Claude Code consumes skills from .claude/skills/<name>/SKILL.md.
• Auto-approval capabilities vary by client; approvals.mode is applied on a best-effort basis.
• Antigravity does not support MCP servers because it only reads from the home directory and does not load repo-local MCP configs.

---

Install

Install once per machine; choose one:

Homebrew (macOS/Linux)

brew install conn-castle/tap/agent-layer

Script (macOS/Linux)

curl -fsSL https://github.com/conn-castle/agent-layer/releases/latest/download/al-install.sh | bash

Verify:

al --version

---

Quick start

Initialize a repo (run from any subdirectory):

cd /path/to/repo
al init

Then run an agent:

al gemini

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.
• 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 (Gemini CLI, Claude Code CLI, Codex, Copilot CLI, VS Code, etc.).

---

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.

Doctor MCP checks

al doctor connects to each enabled MCP server and lists tools. It waits up to 30 seconds per server before warning about connectivity, and prints a short progress indicator while checks run. When config validation fails due to unrecognized keys, al doctor reports the detected key paths, schema hints (allowed keys where applicable), and repair options (al upgrade, al wizard, or manual edits). When agents are enabled, it verifies generated client configs (for example .mcp.json, .gemini/settings.json) are in sync; run al sync if they are missing or stale.

---

FAQ

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.

---

Version pinning (per repo, required)

Version pinning keeps everyone on the same Agent Layer release and lets al download the right binary automatically.

Upgrade contract details (event model, compatibility guarantees, migration rules, OS/shell matrix) are maintained in one canonical location: the upgrade contract (source: site/docs/upgrades.mdx).

When a release version is available, al init writes .agent-layer/al.version (for example, 0.6.0). You can also edit it manually, or set the initial pin with al init --version X.Y.Z (or --version latest).

When you run al inside a repo, it locates .agent-layer/, reads the pinned version when present, and dispatches to that version automatically. al init and al upgrade are exceptions: they run on the invoking CLI version so pin updates and upgrade planning are not blocked by an older repo pin.

By default, al init enables pinning in release builds by writing .agent-layer/al.version. Think of this file like a lockfile: it prevents the repo from silently changing behavior when you update your globally installed al.

Agent Layer treats .agent-layer/al.version as required for supported usage. Do not delete it. If it is missing or invalid, install a release build and run al upgrade to repair it.

Pin format:

• 0.6.0 or v0.6.0 (both are accepted)

Pin parser behavior:

• blank lines and # comments are ignored
• exactly one non-comment version line is expected
• empty/invalid/multi-version pin files produce a warning and dispatch falls back to the current CLI version until repaired

Cache location (per user):

• default: user cache dir (for example ~/.cache/agent-layer/versions/<version>/<os>-<arch>/al-<os>-<arch> on Linux)
• override: AL_CACHE_DIR=/path/to/cache

Overrides:

• AL_VERSION=0.6.0 forces a version (overrides the repo pin)
• AL_NO_NETWORK=1 disables downloads (fails if the pinned version is missing)

---

Updating Agent Layer

Update the global CLI:

• Homebrew: brew upgrade conn-castle/tap/agent-layer (updates the installed formula)
• Script (macOS/Linux): re-run the install script from Install (downloads and replaces al)

Run al upgrade plan and then al upgrade inside the repo to apply template-managed updates. This updates .agent-layer/al.version to match the currently installed al binary and refreshes template-managed files. For a concise runbook (interactive + CI), use the one-page upgrade checklist.

Each al upgrade run writes an automatic snapshot of managed upgrade targets and auto-rolls back if an upgrade step fails. Snapshots are retained under .agent-layer/state/upgrade-snapshots/ for rollback history. To manually restore an applied snapshot, run al upgrade rollback <snapshot-id> (use the JSON filename stem from .agent-layer/state/upgrade-snapshots/ as <snapshot-id>).

To pre-warm a release binary in cache (for offline/air-gapped runs), use al upgrade prefetch --version X.Y.Z.

al upgrade also executes embedded per-release migration manifests before template writes (for example file renames/deletes and config key transitions). If the prior source version cannot be resolved, source-agnostic migrations still run and source-gated migrations are skipped with explicit report output.

Upgrade previews now include line-level diffs in both al upgrade plan and interactive al upgrade prompts. By default, each file preview is truncated to 40 lines; raise this with --diff-lines N when needed. In interactive terminals, diff hunks are colorized for scanability; non-interactive and no-color runs stay plain text.

al doctor always checks for newer releases and warns if you're behind. al init also warns when your installed CLI is out of date, unless you set --version, AL_VERSION, or AL_NO_NETWORK.

Compatibility guarantee:

• Guaranteed upgrade path is sequential release lines only (N-1 to N; example: 0.6.x to 0.7.x).
• Skipping release lines is best effort and may require additional manual migration.
• See the upgrade contract (source: site/docs/upgrades.mdx) for event categories and release-versioned migration rules.

---

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 (Gemini, Claude, Codex, VS Code, Antigravity, 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:

# Preview-only diff against current .agent-layer/config.toml
al wizard --profile /path/to/profile.toml

# Apply profile + run sync
al wizard --profile /path/to/profile.toml --yes

# Remove wizard backups when no longer needed
al wizard --cleanup-backups

Controls:

• Arrow keys: Navigate
• Space: Toggle selection (multi-select)
• Enter: Confirm/Continue
• Esc: Go back to the previous wizard step (first step asks for exit confirmation)
• Ctrl+C: Cancel immediately

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. When prompted for required MCP secrets, type skip to disable that server for this run or cancel to exit without applying changes.

---

What gets created in your repo

al init creates three buckets: user configuration, project memory, and generated client files.

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.

Project memory (required; teams can commit or ignore)

Default instructions and skills rely on these files existing, along with any additional memory files your team adopts.

Common memory files include:

• docs/agent-layer/ISSUES.md
• docs/agent-layer/BACKLOG.md
• docs/agent-layer/ROADMAP.md
• docs/agent-layer/DECISIONS.md
• docs/agent-layer/COMMANDS.md
• docs/agent-layer/CONTEXT.md

Generated client files (gitignored by default)

Generated outputs are written into the repo in client-specific formats (examples):

• Instruction shims: AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md
• MCP + client configs: .mcp.json, .gemini/settings.json, .claude/settings.json, .codex/, .copilot/mcp-config.json
• Shared skills: .agents/skills/
• Claude skills: .claude/skills/
• VS Code integration: .vscode/mcp.json and an Agent Layer-managed block in .vscode/settings.json

---

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:

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

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

[agents.claude]
enabled = true
# model is optional; when omitted, Agent Layer does not pass a model flag and the client uses its default.
# model = "..."
# reasoning_effort is optional for Opus models only.
# reasoning_effort = "medium" # low | medium | high | xhigh | max (custom values pass through with a warning)
# 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).
# 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

[agents.copilot_cli]
enabled = true
# model is optional; when omitted, Agent Layer does not pass a model flag and the client uses its default.
# model = "..."
# reasoning_effort is not currently supported for Copilot CLI in Agent Layer.

[mcp]
# Secrets belong in .agent-layer/.env (never in config.toml).
# MCP servers here are the *external tool servers* that get projected into client configs.
# A fresh `al init` ships no servers; run `al wizard` to pick from a curated catalog (context7, tavily, fetch, playwright, ripgrep, filesystem) or hand-author your own block as shown below.

[[mcp.servers]]
id = "example-api"
enabled = true
transport = "http"
# 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.
# 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,
# "quiet" suppresses agent-layer informational output (warnings, update checks, dispatch banners). `al doctor`
# 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.

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:

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

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 (sends --dangerously-skip-permissions to Claude, --approval-mode=yolo to Gemini, 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.

Instructions: .agent-layer/instructions/

These files are user-editable; customize them for your team's preferences.

• Files are concatenated in lexicographic order
• Use numeric prefixes for stable priority (e.g., 00_core.md, 10_style.md, 20_repo.md)

Skills: .agent-layer/skills/

These files are user-editable; define the workflows you want your agents to run.

Agent Layer aligns with the Agent Skills specification, and al doctor validates configured skills against agentskills-aligned conventions.

• Source format:
  • Directory: .agent-layer/skills/<name>/SKILL.md (canonical; skill.md is accepted as a compatibility fallback)
• Frontmatter fields:
  • Required: name, description
  • Optional: license, compatibility, metadata, allowed-tools
• name validation (al doctor):
  • NFKC-normalized and compared against the canonical source name (filename stem or directory name) using normalization-aware matching
  • Maximum 64 Unicode characters, lowercase letters/digits/hyphens only, and no leading/trailing/consecutive hyphens
• Length limits (al doctor): description max 1024 Unicode characters; compatibility max 500 Unicode characters.
• Size recommendation (al doctor): warns when a skill source exceeds 500 lines.
• Backward compatibility: skills with missing name still load (name derived from path), but al doctor warns.
• Missing or empty description is a load/sync error (fail-loud); it is not warning-only.
• Directory-format skills should use SKILL.md; lowercase skill.md loads but triggers an al doctor warning.
• Shared-skill clients consume these from .agents/skills/<name>/SKILL.md; Claude consumes them from .claude/skills/<name>/SKILL.md.
• Workflow guidance is provided by individual skill sources under .agent-layer/skills/.

Approved commands: .agent-layer/commands.allow

• One command prefix per line.
• Used to generate each client’s “allowed commands” configuration where supported.

---

Skill sync

Skills are synced natively to Agent Skills directories with full subdirectory support (scripts/, references/, assets/). Shared-skill clients use .agents/skills/; Claude uses .claude/skills/. No MCP server is involved; al sync copies skill sources directly into enabled client skill folders. See docs/SKILL-CLIENT-SPEC.md for the source-cited client support matrix.

---

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.

---

Temporary artifacts (agent-only)

Some workflows write agent-only artifacts (plans, task lists, reports). These are not meant for humans to open.

Artifacts always live under .agent-layer/tmp/ and use a unique, concurrency-safe name:

• .agent-layer/tmp/<workflow>.<run-id>.<type>.md
• run-id = YYYYMMDD-HHMMSS-<short-rand> (uses bash $RANDOM; bash is required)
• Multi-file workflows reuse the same run-id for all files.
• Common type values: report, plan, task, context.

Workflows echo the artifact path in the chat output. There are no path overrides or environment variables for this. Artifacts are agent-only and can be ignored; agents may clean up their own plan/task/context files when a workflow completes. If a run is interrupted, leftover files are harmless and optional to delete.

---

CLI overview

Common usage:

al gemini
al claude
al codex
al copilot
al vscode
al antigravity

Passing flags to clients

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.

Examples:

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

--no-sync is an Agent Layer flag and must appear before --; anything after -- is passed directly to the client. For an explicit false value, use --no-sync=false (space-separated values like --no-sync false are not supported and will be passed through).

Other commands:

• al init — initialize .agent-layer/, docs/agent-layer/, and .gitignore
• 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, --diff-lines N to raise per-file preview size; automatic snapshot + rollback on failure)
• al upgrade plan — preview plain-language categorized template/pin changes and readiness actions with line-level diff previews (--diff-lines N to raise per-file preview size)
• al upgrade prefetch — download and cache a release binary (use --version X.Y.Z on dev builds; useful for offline/CI cache warm-up)
• al upgrade rollback <snapshot-id> — restore an applied upgrade snapshot (snapshot IDs are JSON filenames in .agent-layer/state/upgrade-snapshots/; use al upgrade rollback --list to discover available IDs)
• al upgrade repair-gitignore-block — restore .agent-layer/gitignore.block from templates and reapply the root .gitignore managed block
• al sync — regenerate configs without launching a client
• al doctor — check common setup issues and warn about available updates
• al wizard — interactive setup wizard plus profile mode (--profile) and backup cleanup (--cleanup-backups)
• al completion — generate shell completion scripts (bash/zsh/fish, macOS/Linux only)

---

Shell completion (macOS/Linux)

The completion command is available on macOS and Linux only.

“Shell completion output” is a snippet of shell script that enables tab-completion for al in your shell.

Typical behavior:

• al completion bash prints a Bash completion script to stdout
• al completion zsh prints a Zsh completion script to stdout
• al completion fish prints a Fish completion script to stdout
• al completion <shell> --install writes the completion file to the standard user location

This enables:

• al <TAB> to complete supported subcommands (gemini/claude/codex/copilot/vscode/antigravity/sync/…)

Notes:

• Zsh may require adding the install directory to $fpath before compinit (the command prints a snippet when needed).
• Bash completion requires bash-completion to be enabled in your shell.

---

Git ignore defaults

Installer adds a managed .gitignore block that typically ignores:

• .agent-layer/ (except if teams choose to commit it)
• generated client config files/directories (for example .agents/, .gemini/, .claude/, .mcp.json, .codex/, .copilot/, .vscode/mcp.json, .vscode/settings.json, and .github/copilot-instructions.md)

If you choose to commit .agent-layer/, keep .agent-layer/.gitignore so repo-local launchers, template copies, and backups stay untracked.

To commit .agent-layer/, remove the /.agent-layer/ line in .agent-layer/gitignore.block and re-run al sync.

To customize the managed block, edit .agent-layer/gitignore.block and re-run al sync.

.agent-layer/.env is ignored by .agent-layer/.gitignore, not the parent repo .gitignore.

docs/agent-layer/ is created by default; teams may choose to commit it or ignore it.

---

Design goals

• Make installation and day-to-day usage trivial
• Provide consistent core features across clients (instructions, skills, config generation, MCP servers, sync-on-run)
• Reduce moving parts by shipping a single global CLI and keeping .agent-layer/ config-first with minimal repo-local launchers

Changelog

See CHANGELOG.md for release history.

Contributing

Contributions are welcome. Please use the project's issue tracker and pull requests.

Contributor workflows live in docs/DEVELOPMENT.md.

License

See LICENSE.md.

Attributions

• Nicholas Conn, PhD - Conn Castle Studios