Skip to main content

What problem does Agent Layer solve?​

It keeps instructions, skills, MCP servers, and approvals consistent across multiple agents by generating every client config from .agent-layer/.

If you run more than one client, you edit that folder once and review the same files in git.

Does Agent Layer align with the skills standard?​

Yes. Skill parsing and validation follow the agentskills.io specification, including the required uppercase SKILL.md filename.

Does Agent Layer install Claude, Codex, Antigravity, Copilot CLI, Grok, or VS Code?​

No. Agent Layer does not install clients. Install Claude, Codex, Antigravity (agy), Copilot CLI, and Grok yourself and put those CLIs on your PATH. Install VS Code separately as an application; al vscode requires the code command on PATH.

What do I edit vs what gets generated?​

You edit .agent-layer/. Agent Layer generates client-specific outputs in each client's native format when you run al sync or al <client>.

Rule of thumb: generated files include:

  • Instruction shims: AGENTS.md, .claude/CLAUDE.md, .github/copilot-instructions.md
  • Agent config: .mcp.json, .agy/antigravity-cli/settings.json, .agy/antigravity-cli/mcp_config.json, .claude/settings.json, .copilot/mcp-config.json
  • Shared skills: .agents/skills/
  • Claude skills: .claude/skills/
  • Codex config and rules: .codex/
  • VS Code integration: .vscode/mcp.json and a managed block in .vscode/settings.json

If VS Code is enabled, Agent Layer also generates repo-local launchers under .agent-layer/ (for example open-vscode.command and open-vscode.app/). These are kept untracked by .agent-layer/.gitignore.

For full detail, see /docs/reference#sync.

Why does Codex ask me to sign in again per repo?​

The Codex VS Code extension reads CODEX_HOME at startup. Agent Layer sets a repo-specific value via al codex, Codex dispatch, and its VS Code launchers only when local_config_dir = true is enabled under [agents.codex]. In that opt-in mode, Codex authentication state is stored per repository and reauthentication in a different repository is expected.

By default (agents.codex.local_config_dir absent or false), Agent Layer does not set CODEX_HOME; Codex uses its normal global/project config layering and any inherited CODEX_HOME remains user-owned. If you prefer global Codex MCP config in VS Code, see /docs/troubleshooting#global-mcp-server-fallback-for-vs-code-codex.

Does Claude keep separate sign-ins per repo?​

Claude per-repo settings and caches isolation is opt-in. If you set local_config_dir = true under [agents.claude] in config.toml, Agent Layer sets CLAUDE_CONFIG_DIR to a repo-local directory, isolating settings and caches per repository.

Authentication isolation depends on your platform and authentication method. Claude Code stores /login credentials in the macOS Keychain on macOS, so those remain shared. On Linux and Windows, it stores them in .credentials.json under CLAUDE_CONFIG_DIR, so a repo-local directory also isolates those credentials. Environment credentials, apiKeyHelper, and cloud-provider authentication can come from external sources. See Claude Code authentication.

For VS Code, keep [agents.claude_vscode] enabled = true so the extension receives the repo-local CLAUDE_CONFIG_DIR. Without the launcher path, VS Code falls back to global ~/.claude/ behavior.

By default (local_config_dir absent or false), Claude uses your global ~/.claude/ configuration and settings are shared across repositories.

For Claude-specific fallback details, see /docs/troubleshooting#global-config-fallback-for-vs-code-claude.

Should we commit .agent-layer/?​

By default it is gitignored, but teams can choose to commit it (except .agent-layer/.env).

  • Commit when you want shared, stable behavior across the team.
  • Keep it ignored for local-only experiments.

If you commit it, keep .agent-layer/.gitignore so launchers and backups stay untracked.

Where do secrets go?​

Secrets go in .agent-layer/.env and are always gitignored. Only variables with the AL_ prefix are loaded from .env.

Your existing environment variables take precedence over .env entries.

Does Agent Layer use the network?​

Agent Layer itself uses the network for update checks and pinned-version downloads (unless AL_NO_NETWORK=1 is set).

If you enable MCP servers, al doctor and your agents will also connect to those servers.

See /security for a precise breakdown.

Where should I ask for help?​

Open a GitHub issue:

If you're not sure whether something is a bug or "just usage", it's still fine to file an issue. Include your al --version and the output of al doctor (redact secrets).

See /docs/troubleshooting for common fixes first.

How do MCP servers work?​

You define servers in .agent-layer/config.toml. Agent Layer runs exactly the command or URL you configure; it does not install runtimes for you.

If a server uses npx or uvx, you must have those tools installed.

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

If MCP servers that use npx fail to start, VS Code may not see a user-directory Node install. Install Node via Homebrew (brew install node) so GUI apps 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 replaces the managed block on the next al sync, and those extension-written settings are removed.

Use the full repair steps in /docs/troubleshooting#vs-code-settings-disappear-after-sync.

Can I pin a repo to a specific version?​

Yes. .agent-layer/al.version is the repo pin (required). Set it to X.Y.Z or vX.Y.Z, or set an initial pin during al init with --version. You can temporarily override the pin with AL_VERSION.

See /docs/concepts#version-pinning for the full model and tradeoffs.

How do I upgrade a repo?​

Run al update to update the global CLI through its current installation method, then run al upgrade plan and al upgrade inside the repo. This updates the repo pin (.agent-layer/al.version) to match the currently installed al version.

For compatibility guarantees and release migration rules, see /docs/upgrades. For a one-page runbook, use /docs/upgrade-checklist.

What happens if I edit a generated file?​

It will be overwritten the next time you run al sync or al <client>. Always edit the source files in .agent-layer/ instead.

See /docs/reference#sync for what is considered generated.

Can I disable the wizard?​

Yes. Use al init --no-wizard to skip the prompt or run al wizard later if you change your mind.

See /docs/reference#wizard for what it edits.

Is this safe for teams with strict security requirements?​

Yes, if you configure it accordingly. Set approvals.mode to limit automatic approvals, keep command allowlists tight, and enable only trusted MCP servers.

Agent Layer does not install or sandbox MCP servers. It runs exactly what you configure, which makes review and auditing straightforward.

Does Agent Layer ever delete files?​

In the default interactive al upgrade flow, Agent Layer may prompt about unknown files under .agent-layer/ and docs/agent-layer/. Before offering deletion, it lets you add intentional local paths to the gitignored .agent-layer/upgrade-keep-list; .agent-layer/tmp is listed last and unchecked. Kept files and directory subtrees are omitted from future plans and deletion prompts. Agent Layer only deletes remaining paths if you explicitly approve. For non-interactive or explicit-category apply (e.g., --yes --apply-managed-updates), unknown-file deletions require the separate --apply-deletions flag, which also respects the keep list.

Files under .agent-layer/tmp/ (ephemeral agent run artifacts: plans, reports, scratch dumps) are protected by stricter rules. The interactive prompt requires a destructive double-confirm that defaults to "no", unless .agent-layer/tmp is listed in .agent-layer/upgrade-keep-list. Non-interactive deletion requires the dedicated --apply-tmp-deletions flag — --apply-deletions alone never touches tmp content. The interactive "delete all unknowns?" choice is also scoped to skip tmp; the grouped tmp prompt fires separately when tmp is not kept. See /docs/reference.

Will rollback restore files I had under .agent-layer/tmp/?​

No. Pre-upgrade snapshots intentionally exclude .agent-layer/tmp/ so they stay small (tmp can accumulate hundreds of MB of agent run artifacts). al upgrade rollback <snapshot-id> will not recreate plans, reports, or scratch files that were under tmp. If you need to keep an in-progress agent artifact across an upgrade, copy it out of .agent-layer/tmp/ first.

See /docs/upgrades for rollback scope and the rest of the upgrade policy.