Overview
Agent Layer is a small CLI that keeps AI-assisted development consistent across tools. You define agent instructions, approvals, and MCP servers once in a repo-local .agent-layer/ folder, and al generates each client's native config on demand.
The payoff is fewer surprises: the same repo behaves the same whether you launch Gemini, Claude, Codex, VS Code, or Antigravity. No copying configuration between clients. No gradual drift. Just one place to review and refine how your agents work.
Start with Getting started, then use Concepts and Reference as you customize. Troubleshooting is a fast path when something breaks. For upgrade policy, compatibility guarantees, and migration rules, use Upgrades.
What you get
- A single source of truth you can treat like code (reviewable, shareable, easy to audit).
- Deterministic generated outputs that are safe to delete and recreate.
- Guardrails for autonomy: choose what can run automatically and what must be approved.
- Optional version pinning so a team stays on the same behavior across machines and CI.
Who this is for
- You use more than one agent client and want them to behave consistently.
- You want repo-specific safety rules instead of one global configuration for every project.
- You want to add tools (MCP servers) once and have them available everywhere.
- You want agent setup to be explicit and reviewable, not a collection of local tweaks.
Recommended path
- Getting started - run your first agent
- Concepts - learn the mental model and safety boundaries
- Reference - config, environment variables, and CLI behavior
- Troubleshooting - common errors and fixes
- Upgrades - upgrade event model, compatibility guarantees, and migration rules
Documentation map
Getting started
Install Agent Layer, initialize your first repo, and understand what gets generated. Includes: Quick start, Repo layout, and CLI command map.
Concepts
The mental model and safety boundaries that keep agents consistent. Includes: Single source of truth, Approvals and safety, MCP servers, Project memory, and Version pinning.
Reference
Authoritative configuration, environment variables, and CLI behavior. Includes: Configuration, Environment variables, and the CLI guide.
Troubleshooting
Fast fixes for install, config, and MCP issues. Includes: Install issues, Configuration errors, MCP server issues, and Offline/pinning.
Upgrades
Canonical upgrade contract and release migration expectations. Includes: Upgrade event model, Compatibility guarantees, Migration rules by release, docs version retention and access, and OS and shell capability matrix.
Other resources
If Agent Layer is useful for your team, consider starring the repository to improve discoverability for new users.