atlas-guardrails

The Problem

Coding agents (Claude Code, Cursor, Windsurf) are fast, but they have the memory of a goldfish. They:

1. Re-invent the wheel: Creating utils/date.ts when lib/time.ts already exists.
2. Hallucinate APIs: Guessing method signatures instead of looking them up.
3. Drift APIs: Changing public exports without you realizing it until CI explodes.

The Solution: Atlas

Atlas is a local-first guardrail that forces agents to "read the map" before they write code. It indexes your repo, packs relevant context deterministically, and screams at agents when they try to duplicate code or break APIs.

Installation & Integration 🤖

Atlas is built for AI Agents, not humans. To give your agent "eyes" into your repository, choose your client below:

gemini extensions install https://github.com/marcusgoll/atlas-guardrails

gemini mcp add atlas -- command npx -y atlas-guardrails mcp

# In Claude Code:
/plugin marketplace add marcusgoll/atlas-guardrails
/plugin install atlas-guardrails@marcusgoll/atlas-guardrails

claude mcp add atlas -- npx -y atlas-guardrails mcp

# From atlas-guardrails repo or create manually
cp .cursor/mcp.json ~/.cursor/mcp.json

{
  "mcpServers": {
    "atlas": {
      "command": "npx",
      "args": ["-y", "atlas-guardrails", "mcp"]
    }
  }
}

npm install -g atlas-guardrails

atlas update

Agent Workflow

Once installed, your AI agent will follow this deterministic loop:

1. Map the Terrain: Agent calls atlas_index to build/update the symbol graph.
2. Gather Context: Agent calls atlas_pack with your task description. It receives a token-optimized pack of relevant files and their dependency trails.
3. Prevent Duplication: Before the agent writes a new helper, it calls atlas_find_duplicates to see if the code already exists.
4. Enforce Guardrails: Agent runs atlas check (or you run it in CI) to ensure no public API drift occurred.

Agent Instruction Files

To ensure your AI agent uses Atlas correctly, add an instruction file to your project root. The agent reads this file automatically and follows the guardrails.

Quick Setup

Copy the template to your project:

# For Claude Code
curl -o CLAUDE.md https://raw.githubusercontent.com/marcusgoll/atlas-guardrails/master/CLAUDE.md

# For Gemini CLI
curl -o GEMINI.md https://raw.githubusercontent.com/marcusgoll/atlas-guardrails/master/GEMINI.md

Template Content

Your instruction file should include these core rules:

# Atlas Guardrails