{
"markdown": "\n\n# ATLAS GUARDRAILS - Stop the Entropy \n\n**Stop LLM agents from turning your codebase into a landfill.**\n\n[](https://www.npmjs.com/package/atlas-guardrails)\n[](https://github.com/marcusgoll/atlas-guardrails/actions)\n[](LICENSE)\n[](https://www.npmjs.com/package/atlas-guardrails)\n\n\n\n\n[Quick Start](#installation--integration-) •\n[Features](#features) •\n[MCP Support](#mcp-support) •\n[Contributing](#contributing)\n\n
\n\n---\n\n## The Problem\n\nCoding agents (Claude Code, Cursor, Windsurf) are fast, but they have the memory of a goldfish. They:\n1. **Re-invent the wheel**: Creating `utils/date.ts` when `lib/time.ts` already exists.\n2. **Hallucinate APIs**: Guessing method signatures instead of looking them up.\n3. **Drift APIs**: Changing public exports without you realizing it until CI explodes.\n\n## The Solution: Atlas\n\nAtlas 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.\n\n## Installation & Integration 🤖\n\nAtlas is built for **AI Agents**, not humans. To give your agent \"eyes\" into your repository, choose your client below:\n\n\nGemini CLI
\n\nInstall Atlas as a native extension:\n```bash\ngemini extensions install https://github.com/marcusgoll/atlas-guardrails\n```\n\n**If installation fails**, add it as a manual MCP extension:\n```bash\ngemini mcp add atlas -- command npx -y atlas-guardrails mcp\n```\n**Capabilities added:** `atlas_index`, `atlas_pack`, `atlas_find_duplicates`.\n \n\n\nClaude Code
\n\n**Option A**: Add as marketplace + install plugin:\n```bash\n# In Claude Code:\n/plugin marketplace add marcusgoll/atlas-guardrails\n/plugin install atlas-guardrails@marcusgoll/atlas-guardrails\n```\n\n**Option B**: Add MCP server directly:\n```bash\nclaude mcp add atlas -- npx -y atlas-guardrails mcp\n```\n\n**What you get:**\n- MCP tools: `atlas_index`, `atlas_pack`, `atlas_find_duplicates`\n- Slash commands: `/atlas-pack`, `/atlas-check`, `/atlas-duplicates`\n \n\n\nCursor / Windsurf
\n\n**Option A**: Copy the config file (recommended):\n```bash\n# From atlas-guardrails repo or create manually\ncp .cursor/mcp.json ~/.cursor/mcp.json\n```\n\n**Option B**: Add via IDE settings:\n1. Open **Settings** -> **Features** -> **MCP**.\n2. Click **+ Add Server**:\n - **Name**: `Atlas`\n - **Type**: `command`\n - **Command**: `npx -y atlas-guardrails mcp`\n \n\n\nClaude Desktop
\n\nAdd Atlas to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"atlas\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"atlas-guardrails\", \"mcp\"]\n }\n }\n}\n```\n \n\n\nDeveloper / Standalone CLI
\n\nTo use Atlas as a standalone terminal tool (or to enable the global `atlas` command):\n```bash\nnpm install -g atlas-guardrails\n```\n*Note: If you are on a version < 1.0.15, run this one last time to enable auto-updates.*\n\nKeep Atlas current with:\n```bash\natlas update\n```\n \n\n---\n\n## Agent Workflow\n\nOnce installed, your AI agent will follow this deterministic loop:\n\n1. **Map the Terrain**: Agent calls `atlas_index` to build/update the symbol graph.\n2. **Gather Context**: Agent calls `atlas_pack` with your task description. It receives a token-optimized pack of relevant files and their dependency trails.\n3. **Prevent Duplication**: Before the agent writes a new helper, it calls `atlas_find_duplicates` to see if the code already exists.\n4. **Enforce Guardrails**: Agent runs `atlas check` (or you run it in CI) to ensure no public API drift occurred.\n\n---\n\n## Agent Instruction Files\n\nTo 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.\n\n| Client | File | Notes |\n|--------|------|-------|\n| Claude Code | `CLAUDE.md` | Auto-loaded by Claude |\n| Gemini CLI | `GEMINI.md` | Referenced via `gemini-extension.json` |\n| Generic | `AGENTS.md` | Works with most agents |\n\n### Quick Setup\n\nCopy the template to your project:\n\n```bash\n# For Claude Code\ncurl -o CLAUDE.md https://raw.githubusercontent.com/marcusgoll/atlas-guardrails/master/CLAUDE.md\n\n# For Gemini CLI\ncurl -o GEMINI.md https://raw.githubusercontent.com/marcusgoll/atlas-guardrails/master/GEMINI.md\n```\n\n### Template Content\n\nYour instruction file should include these core rules:\n\n```markdown\n# Atlas Guardrails\n\n## Rules for Agent\n\n1. **Pack Before Editing**: Run `atlas_pack(task=\"...\")` before modifying code.\n2. **Search Before Creating**: Run `atlas_find_duplicates(intent=\"...\")` before creating new utilities.\n3. **Respect Guardrails**: If `atlas check` fails, fix the drift.\n\n## MCP Tools\n\n- `atlas_index()` - Rebuild the symbol index\n- `atlas_pack(task, budget)` - Get context for a task\n- `atlas_find_duplicates(intent)` - Find existing code\n```\n\n### Why This Matters\n\nWithout instruction files, agents will:\n- Skip the `atlas_pack` step and read random files\n- Create duplicate utilities instead of reusing existing code\n- Ignore API drift warnings\n\nThe instruction file makes Atlas usage **mandatory** for the agent.\n\n---\n\n## Documentation & Specs\n\n* [INTEGRATION.md](./INTEGRATION.md) - Full MCP & API Schema.\n* [CLAUDE.md](./CLAUDE.md) - Instruction set for Claude.\n* [GEMINI.md](./GEMINI.md) - Instruction set for Gemini.\n* [API Documentation](./docs/index.html) - TypeDoc output.\n\n## Contributing\n\nWe aim for **>80% test coverage** to keep the guardrails stable.\n1. Fork & Clone.\n2. `npm install`\n3. `npm test`\n4. PR.\n\n## License\n\nMIT © [Marcus Gollahon](https://github.com/marcusgoll)\n",
"bytes": 6187,
"sha": "8efb1933987ce91dcc587264ed67fe3cfc1d829270c2aa7b2d1f2a0e32bfd30c",
"repo_slug": "marcusgoll/atlas-guardrails",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_marcusgoll_atlas_guardrails_5d16dba8/readme"
}