ATLAS GUARDRAILS - Stop the Entropy

Stop LLM agents from turning your codebase into a landfill.

Quick Start • Features • MCP Support • Contributing

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:

Install Atlas as a native extension:

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

If installation fails, add it as a manual MCP extension:

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

Capabilities added: atlas_index, atlas_pack, atlas_find_duplicates.

Install Atlas as a native skill:

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

Claude will automatically utilize SKILL.md and CLAUDE.md context to manage your repo entropy.

Add Atlas as an MCP Server in your IDE settings:

1. Open Settings -> Features -> MCP.
2. Click + Add Server:
   • Name: Atlas
   • Type: command
   • Command: npx -y atlas-guardrails mcp

Add Atlas to your claude_desktop_config.json:

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

To use Atlas as a standalone terminal tool (or to enable the global atlas command):

npm install -g atlas-guardrails

Note: If you are on a version < 1.0.15, run this one last time to enable auto-updates.

Keep Atlas current with:

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.

Documentation & Specs

• INTEGRATION.md - Full MCP & API Schema.
• CLAUDE.md - Instruction set for Claude.
• GEMINI.md - Instruction set for Gemini.
• API Documentation - TypeDoc output.

Contributing

We aim for >80% test coverage to keep the guardrails stable.

1. Fork & Clone.
2. npm install
3. npm test
4. PR.

License

MIT © Marcus Gollahon