---

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 CLI

Install Atlas as a native extension:
``bash
gemini extensions install https://github.com/marcusgoll/atlas-guardrails
`

If installation fails, add it as a manual MCP extension:
`bash
gemini mcp add atlas -- command npx -y atlas-guardrails mcp
`
Capabilities added: atlas_index, atlas_pack, atlas_find_duplicates.






Claude Code

Install Atlas as a native skill:
`bash
claude extensions install https://github.com/marcusgoll/atlas-guardrails
`
Claude will automatically utilize SKILL.md and CLAUDE.md context to manage your repo entropy.






Cursor / Windsurf

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






Claude Desktop

Add Atlas to your claude_desktop_config.json:

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






Developer / Standalone CLI

To use Atlas as a standalone terminal tool (or to enable the global atlas command):
`bash
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:
`bash
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