### One-time Setup Script

Source: https://github.com/conn-castle/agent-layer/blob/main/docs/DEVELOPMENT.md

Executes the setup script for a new clone of the repository. This should be run once after cloning.

```bash
./scripts/setup.sh
```

--------------------------------

### Generated Client Outputs Example

Source: https://github.com/conn-castle/agent-layer/blob/main/site/docs/getting-started.mdx

This section lists examples of generated files, including instruction shims and client-specific configurations, which should not be edited directly.

```text
# Instruction shims (generated from .agent-layer/instructions/*.md)
AGENTS.md
CLAUDE.md
.github/copilot-instructions.md

# Client configs and artifacts (generated based on enabled clients)
.agents/skills/
.agy/antigravity-cli/settings.json
.agy/antigravity-cli/mcp_config.json
.claude/settings.json
.claude/skills/
.mcp.json
.codex/
.copilot/mcp-config.json
.vscode/mcp.json
.vscode/settings.json

# Repo-local launchers (VS Code, when enabled)
.agent-layer/open-vscode.command
.agent-layer/open-vscode.desktop
.agent-layer/open-vscode.sh
.agent-layer/open-vscode.app/
```

--------------------------------

### Verify Go Installation

Source: https://github.com/conn-castle/agent-layer/blob/main/docs/DEVELOPMENT.md

Confirms that Go version 1.26.0 or higher is installed and accessible in your PATH.

```bash
go version
```

--------------------------------

### Download and Inspect Install Script

Source: https://github.com/conn-castle/agent-layer/blob/main/site/pages/install.mdx

If you prefer not to pipe the script directly, download it first to inspect its contents before execution.

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

--------------------------------

### Agent Layer Configuration Example

Source: https://github.com/conn-castle/agent-layer/blob/main/site/docs/reference.mdx

This TOML snippet shows a typical configuration for Agent Layer, including approval modes, agent enablement, and MCP server setup. Ensure secrets are stored in .agent-layer/.env, not here.

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

[agents.antigravity]
enabled = true

[agents.claude]
enabled = true
# model = "..."
# reasoning_effort is optional for Opus models only.
# reasoning_effort = "medium" # low | medium | high | xhigh | max (custom values pass through with a warning)
# 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).
# Object values are deep-merged into .claude/settings.json; arrays and scalar values are replaced at their key.
# Overlapping managed keys, such as permissions.allow, override Agent Layer-managed
# values and trigger a sync warning. permissions.deny is additive and does not warn.
# [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.
# Agent Layer already writes [projects."<repo root>"] trust_level = "trusted".
# [agents.codex.agent_specific]
# [agents.codex.agent_specific.features]
# apps = false              # disable built-in Codex apps (Github, Gmail, etc.) to reduce tool surface
# multi_agent = true
# prevent_idle_sleep = true

[agents.vscode]
enabled = true

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

[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,

```

--------------------------------

### Stdio MCP Server Configuration

Source: https://github.com/conn-castle/agent-layer/blob/main/site/docs/reference.mdx

Example TOML configuration for an MCP server using the stdio transport. Ensure 'npx' is in your PATH and the specified package is installed.

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

--------------------------------

### Run Agent Layer Wizard

Source: https://github.com/conn-castle/agent-layer/blob/main/README.md

Launches the interactive setup wizard. Supports profile mode (`--profile`) and backup cleanup (`--cleanup-backups`).

```bash
al wizard
```

--------------------------------

### Install Agent Layer via Homebrew

Source: https://github.com/conn-castle/agent-layer/blob/main/site/pages/index.mdx

Install the agent-layer CLI tool using Homebrew. This is the first step to using agent-layer.

```bash
# Install agent-layer
brew install conn-castle/tap/agent-layer
```

--------------------------------

### Verify pre-commit Installation

Source: https://github.com/conn-castle/agent-layer/blob/main/docs/DEVELOPMENT.md

Checks if the pre-commit framework is installed, which is recommended for local Git hooks.

```bash
pre-commit --version
```

--------------------------------

### Install Xcode Command Line Tools

Source: https://github.com/conn-castle/agent-layer/blob/main/docs/DEVELOPMENT.md

Installs necessary command-line tools for macOS development, including Git. Run this on a fresh macOS machine.

```bash
xcode-select --install
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/conn-castle/agent-layer/blob/main/docs/agent-layer/COMMANDS.md

Installs pre-commit hooks to manage code quality and consistency. Requires pre-commit to be installed.

```bash
pre-commit install --install-hooks
```

--------------------------------

### Install Pinned Dependencies

Source: https://github.com/conn-castle/agent-layer/blob/main/docs/DEVELOPMENT.md

Installs all pinned development dependencies, such as linters and test tools, into the .tools/bin directory. Run this once per clone if tools are missing.

```bash
make tools
```

--------------------------------

### Install Shell Completion Scripts

Source: https://github.com/conn-castle/agent-layer/blob/main/README.md

Writes the completion file to the standard user location for the specified shell.

```bash
al completion <shell> --install
```

--------------------------------

### Example Chat Output Summary

Source: https://github.com/conn-castle/agent-layer/blob/main/internal/templates/skills/audit-and-fix-uncommitted-changes/SKILL.md

An example of the summary presented to the user in chat after the skill run, indicating convergence status, findings, and fix counts.

```markdown
- 2 rounds to converge (Round 2 applied zero Critical/High fixes)
- 12 findings from 5 parallel reviewers
- 5 accepted and fixed, 6 rejected, 1 deferred
```

--------------------------------

### Local Development Setup and Run

Source: https://github.com/conn-castle/agent-layer/blob/main/site/pages/contributing.mdx

Execute these commands from the repository root to set up the development environment and run the project locally. Use `make test` for faster iteration cycles.

```bash
./scripts/setup.sh
make dev
```

--------------------------------

### Pre-commit Hook Installation Troubleshooting

Source: https://github.com/conn-castle/agent-layer/blob/main/docs/DEVELOPMENT.md

Commands to unset `core.hooksPath` if pre-commit installation fails with a 'Cowardly refusing to install hooks' error. This ensures hooks are installed correctly for the repository.

```bash
git config --show-origin --get core.hooksPath
git config --unset-all core.hooksPath
# If it was set globally instead:
# git config --global --unset-all core.hooksPath
./scripts/setup.sh
```

--------------------------------

### Initialize a New Repository with Agent Layer CLI

Source: https://github.com/conn-castle/agent-layer/blob/main/docs/DEVELOPMENT.md

Initializes a new repository with the Agent Layer CLI, creating necessary configuration directories like .agent-layer/ and docs/agent-layer/.

```bash
go run ./cmd/al init
```

--------------------------------

### Install and Verify Agent Layer Version

Source: https://github.com/conn-castle/agent-layer/blob/main/docs/RELEASE.md

Installs a specific version of the agent layer and verifies the installation by checking the version number. Ensure the `VERSION` variable is set to the desired release tag.

```bash
VERSION="vX.Y.Z"
tmp_dir="$(mktemp -d)"
cd "$tmp_dir"
curl -fsSL https://github.com/conn-castle/agent-layer/releases/latest/download/al-install.sh \
  | bash -s -- --version "$VERSION"
~/.local/bin/al --version
```

--------------------------------

### Example MCP Server Configuration with AL_REPO_ROOT

Source: https://github.com/conn-castle/agent-layer/blob/main/README.md

This TOML snippet demonstrates how to configure an MCP server, specifically the 'filesystem' type, using the built-in ${AL_REPO_ROOT} placeholder for its command arguments. This placeholder expands to the absolute repository root during agent layer sync and doctor operations.

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

--------------------------------

### General Client Launch Command

Source: https://github.com/conn-castle/agent-layer/blob/main/site/docs/getting-started.mdx

The `al <client>` command is a versatile entry point that first syncs configurations and then launches the specified client.

```bash
al <client>
```

--------------------------------

### Launch Client with Arguments

Source: https://github.com/conn-castle/agent-layer/blob/main/site/docs/reference.mdx

Launches a specified client and forwards additional arguments to it. Use '--' to separate Agent Layer flags from client arguments.

```bash
al claude -- --help
```

--------------------------------

### Install Agent Layer with Homebrew

Source: https://github.com/conn-castle/agent-layer/blob/main/site/pages/install.mdx

Use this command to install the Agent Layer CLI if you are using Homebrew on macOS or Linux.

```bash
brew install conn-castle/tap/agent-layer
```

--------------------------------

### Initialize and Sync Scratch Repo

Source: https://github.com/conn-castle/agent-layer/blob/main/site/pages/contributing.mdx

Run these commands within a temporary directory to validate seeded outputs after changing template files or sync behavior. This ensures generated outputs are deterministic.

```bash
mkdir -p tmp/dev-repo
cd tmp/dev-repo
go run ../../cmd/al init
go run ../../cmd/al sync
```

--------------------------------

### Stdio MCP Server Configuration

Source: https://github.com/conn-castle/agent-layer/blob/main/site/docs/concepts.mdx

Defines an example stdio MCP server in the `config.toml` file. Requires a command and arguments to execute locally, such as the filesystem server.

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

--------------------------------

### Skill Markdown Frontmatter Example

Source: https://github.com/conn-castle/agent-layer/blob/main/site/docs/reference.mdx

Example of a skill definition using Markdown frontmatter, specifying required 'name' and 'description' fields.

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

--------------------------------

### Example TOML Configuration for Stdio MCP Server

Source: https://github.com/conn-castle/agent-layer/blob/main/README.md

Configure a local MCP server using standard input/output. Specify the command to run, its arguments, and environment variables, including a token from an environment variable.

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

--------------------------------

### Install Shell Completion Scripts

Source: https://github.com/conn-castle/agent-layer/blob/main/site/docs/reference.mdx

Installs shell completion scripts for the current shell. Supported shells include bash, zsh, and fish.

```bash
al completion zsh --install
```

--------------------------------

### Display General Help

Source: https://github.com/conn-castle/agent-layer/blob/main/site/docs/reference.mdx

Displays general help information for the Agent Layer CLI, listing available commands and global flags.

```bash
al --help
```

--------------------------------

### Initialize Agent Layer in a Repository

Source: https://github.com/conn-castle/agent-layer/blob/main/README.md

Run this command from any subdirectory within your repository to initialize Agent Layer. It prompts to run `al wizard` by default.

```bash
cd /path/to/repo
al init
```

--------------------------------

### Install 'code' Command in VS Code PATH

Source: https://github.com/conn-castle/agent-layer/blob/main/README.md

If using CLI-based launchers, install the 'code' command from within VS Code. This makes the VS Code command-line interface available on your system's PATH.

```bash
Cmd+Shift+P -> "Shell Command: Install 'code' command in PATH"
```

```bash
Ctrl+Shift+P -> "Shell Command: Install 'code' command in PATH"
```

--------------------------------

### List Available Agent Layer Upgrade Snapshots

Source: https://github.com/conn-castle/agent-layer/blob/main/site/docs/upgrade-checklist.mdx

Execute this command to list all available snapshots for rolling back an upgrade.

```bash
al upgrade rollback --list
```

--------------------------------

### Core Release Commands

Source: https://github.com/conn-castle/agent-layer/blob/main/docs/RELEASE.md

Commands to checkout main, fetch updates, tag the release, and push to origin. Ensure the working tree is clean before proceeding.

```bash
VERSION="vX.Y.Z"

# Ensure main is current and clean
git checkout main
git fetch origin
git pull --ff-only origin main
git status --porcelain

# Tag and push
git tag -a "$VERSION" -m "$VERSION"
git push origin main
git push origin "$VERSION"

# Release assets are built by the GitHub Actions workflow.
```

--------------------------------

### Perform Agent Layer Health Check

Source: https://github.com/conn-castle/agent-layer/blob/main/README.md

Run this command for an optional health check of your Agent Layer setup.

```bash
al doctor
```