Atlas Claude

Autonomous Task, Learning, and Agent System

A self-evolving AI operating system for Claude Code It doesn't just follow instructions — it learns, adapts, and grows itself.

What • Install • Commands • Behaviors • Flow • Hooks • Architecture

---

What is ATLAS?

Most Claude Code setups are a CLAUDE.md with some rules. ATLAS is a full infrastructure layer — 20 lifecycle hooks, 74 specialized agents, a persistent knowledge graph, an in-session action graph, and self-evolving skill/memory systems that let Claude Code grow its own capabilities. Since v7.0, drift catches itself: telemetry feeds an /observe dashboard and a session-start drift-proposer that surfaces fixable problems before you ask.

What you type:

build a REST API for user management

What ATLAS does:

1. Scores complexity → TEAM (score: 9)
2. Spawns 3 agents: architect, implementer, tester
3. Routes to Tier 3 (Sonnet) for cost efficiency
4. Loads relevant skills (FastAPI, security, testing)
5. Executes with parallel agents in isolated worktrees
6. Security scans before marking done
7. Learns from any mistakes for next time

       ┌──────────────────────────────────┐
       │            A T L A S             │
       ├──────────────────────────────────┤
       │                                  │
       │  /new  /resume  /task  /done     │ ← You
       │         │                        │
       │         ▼                        │
       │  ┌───────────┐  ┌───────────┐    │
       │  │   Flow    │  │   Smart   │    │ ← Routing
       │  │  System   │  │   Swarm   │    │
       │  └─────┬─────┘  └─────┬─────┘    │
       │        ▼              ▼          │
       │  ┌──────────────────────────┐    │
       │  │ 45 Skills · 74 Agents    │    │ ← Execution
       │  │ 20 Hooks  · 3 Rule Files │    │
       │  └──────────┬───────────────┘    │
       │             ▼                    │
       │  ┌──────────────────────────┐    │
       │  │ Learn · Evolve · Grow    │    │ ← Growth
       │  └──────────────────────────┘    │
       └──────────────────────────────────┘

> TL;DR — It continues its own work when context runs out. It deploys agent teams based on task complexity. It creates new skills when it finds capability gaps. It learns from mistakes across sessions.

---

Quick Start

# Clone
git clone https://github.com/Leo-Atienza/atlas-claude.git

# Install (safe — never overwrites existing files)
cd atlas-claude && bash install.sh

# Verify system health
bash ~/.claude/scripts/smoke-test.sh

See [examples/](examples/) for a starter settings.json template with sensible defaults.

---

The Entry Points

Everything funnels through a small set of entry commands. You never need to think about the 45 active skills, 74 agents, or 67 commands underneath.

| Command | Plain English | What Happens Under the Hood | |:-------:|:-------------|:---------------------------| | /new | "build X", "create X" | Classifies task → auto-detects depth → initializes Flow → routes to agents | | /resume | "continue", "pick up" | Reads handoff + state files in precedence order → restores full context → continues | | /task | "fix X", "add X" | One-off routing → complexity scoring → direct execution | | /done | "wrap up" | Reflects → captures knowledge → saves state → commits | | /ship | "push this" | Commits → pushes → opens PR → security scan | | /dream | "consolidate" | Deep memory merge → prune stale → resolve conflicts → reindex | | /handoff | "end session" | Build + test → commit → push → chat handoff block | | /audit | "check this repo" | Wave-based systematic audit with verified fixes | | /health | "system status" | Validates hooks, counts, drift; updates SYSTEM_VERSION | | /system-doctor | "validator scoreboard" | Runs all 9 scripts/validate-*.js validators (incl. references integrity check), emits unified ✓/✗ scoreboard; test-validators.js regression-tests the validators themselves | | /observe | "how's the system?" | 6-section dashboard (tool health, safety hooks, skills, tasks, action graph, cleanup) | | /apply-drift-fix | "fix the drift" | Reads last drift proposal, routes to archive/disable/retrigger action |

---

Autonomous Behaviors

These happen without user action. ATLAS monitors, decides, and acts.

Auto-Continuation

When context nears limits, ATLAS writes a structured handoff so a new session can pick up exactly where it left off. Handoffs live per-CWD at ~/.claude/handoffs/.md.

Smart Swarm

Every task is scored across multiple dimensions on a 0-15 scale:

 File Scope ──┐
 Concerns ────┤
 Risk ────────┼── Score ──→ SOLO (0-4)  │ DUO (5-7)  │ TEAM (8-11) │ SWARM (12-15)
 Isolation ───┤            execute      2 agents      3-4 agents    wave execution
 Urgency ─────┘            directly     in parallel   + coordinator  + worktrees

Combined with three-tier model routing — Haiku for simple subtasks, Sonnet for implementation, Opus for architecture — to cut token costs without sacrificing quality.

Atlas Intelligence Layer

Three persistence systems with strict boundaries:

Memory  (projects/*/memory/)   user profile, feedback, project context, external refs
Knowledge Store  (topics/)     KNOWLEDGE-NNN with type: pattern|solution|error|preference|failure
Atlas KG  (atlas-kg/)          facts NOT derivable from git/code — architectural truths

Plus an in-session action graph (atlas-action-graph/) that tracks reads/searches, feeds a duplicate-read advisory, and surfaces a hot-set digest across PreCompact and SessionStart.

Defense-in-Depth Security

Layer 1 (PreToolUse):  context-guard.js — secrets, context budget, duplicate-read advisory
Layer 2 (PreToolUse):  cctools safety hooks — bash command patterns, file length, env reads, rm-block
Layer 3 (PreToolUse):  pre-commit-gate.js — warns if build+test wasn't run before commit
Layer 4 (PostToolUse): tsc-check.js + post-tool-monitor.js — type errors + failure/efficiency telemetry
Layer 5 (PostToolUseFailure): tool-failure-handler.js — circuit breaker, MCP classification

Code Graph Integration (CRG)

When a project has .code-review-graph/graph.db, ATLAS prefers the CRG MCP tools (get_minimal_context, query_graph, get_impact_radius, semantic_search_nodes) over Glob/Grep. The graph auto-updates on every Write/Edit via a PostToolUse hook. Falls back to graphify (graphify-out/graph.json) for mixed-corpus projects.

---

The Flow System

One unified workflow system with 21 Flow commands:

Trivial ─────→ Quick ─────→ Standard ─────→ Deep ─────→ Epic
(
PageCountHighlights
Web & Frontend (Page 1)34React, Next.js, animation, design systems, web testing, security
Backend & Tools (Page 2)22FastAPI, Express, deployment, workflow, MCP tooling
Native & Cross-Platform (Page 3)10Expo, Tauri, SwiftUI, Jetpack Compose, Maestro

Archived skills live under `skills/ARCHIVE-DIRECTORY.md` (7 domain bundles). Third-party skill packs on disk include `trailofbits-security`, `fullstack-dev`, `context-engineering-kit`, `compound-engineering`, and `cctools`.

---

## Architecture

~/.claude/ ├── CLAUDE.md # Slim core instructions (~8KB) ├── ARCHITECTURE.md # System architecture reference ├── REFERENCE.md # Slash commands, MCP patterns, generators ├── SYSTEMVERSION.md # Component inventory + health (auto-updated) ├── SYSTEMCHANGELOG.md # Infrastructure version history ├── settings.json # Hook wiring, permissions, env vars │ ├── hooks/ # 20 lifecycle hooks (30 files incl. helpers) │ ├── lib.js # Shared utilities (all Node hooks import this) │ ├── context-guard.js # PreToolUse — duplicate-read + security gate │ ├── post-tool-monitor.js # PostToolUse — telemetry + action-graph logging │ ├── tool-failure-handler.js # PostToolUseFailure — circuit breaker │ ├── pre-commit-gate.js # PreToolUse — build+test reminder │ ├── tsc-check.js # PostToolUse — TypeScript diagnostics │ ├── skill-usage-log.js # PreToolUse Skill — usage telemetry (v7.0) │ ├── cleanup-runner.js # SessionStart — 13 declarative cleanup rules │ ├── cleanup-config.json # Cleanup engine rules (per-mode) │ ├── drift-proposer.js # SessionStart — DRIFT advisor (v7.0) │ ├── drift-thresholds.json # Per-channel cooldowns + silenced-kinds │ ├── atlas-kg.js # Temporal knowledge graph module │ ├── atlas-extractor.js # Regex classifier (text → KNOWLEDGE-NNN with type:) │ ├── atlas-action-graph.js # In-session retrieval log + priority queue │ ├── session-start.sh # SessionStart — handoff + KG + carryover │ ├── session-stop.sh # Stop — handoff + KG capture + stats rollup │ ├── statusline.js # StatusLine — context bar, task, call count │ └── cctools-safety-hooks/ # Python safety blockers (bash, rm, env, file len) │ ├── skills/ # 45 active skill entries (in skills/ACTIVE-DIRECTORY.md, 47 in archived/) │ ├── ACTIVE-DIRECTORY.md # Index of active skills │ ├── ACTIVE-PAGE-1-.md # Web + frontend skills (34) │ ├── ACTIVE-PAGE-2-.md # Backend + tools skills (22) │ ├── ACTIVE-PAGE-3-.md # Native + cross-platform skills (10) │ ├── ARCHIVE-DIRECTORY.md # Archived skills by domain bundle │ ├── RULES-GIT.md # On-demand git workflow rules │ ├── RULES-SECURITY.md # On-demand security rules + triggers │ ├── RULES-TESTING.md # On-demand testing rules │ └── [domain]/SKILL.md # Individual skill definitions │ ├── topics/ # Knowledge store (74 entries, v7.0.1 unified namespace) │ ├── KNOWLEDGE-DIRECTORY.md # Index — IDs are KNOWLEDGE-NNN with type: field │ ├── KNOWLEDGE-PAGE-1-patterns.md # type: pattern (30) │ ├── KNOWLEDGE-PAGE-2-solutions.md # type: solution (17) │ ├── KNOWLEDGE-PAGE-3-errors.md # type: error (13) │ ├── KNOWLEDGE-PAGE-4-preferences.md # type: preference (8) │ └── KNOWLEDGE-PAGE-5-failures.md # type: failure (6) │ ├── commands/ # 67 slash commands (top-level + namespaced plugin/flow/hackathon) │ ├── new.md, resume.md, ... # Top-level entry points (incl. v7.0 /observe + /apply-drift-fix) │ └── flow/.md # 21 Flow workflow commands │ ├── agents/ # 74 specialized agents │ ├── flow-.md # Flow agents (planner, executor, verifier, ...) │ ├── smart-swarm-coordinator # Multi-agent orchestrator │ └── [domain]/.md # Domain specialists │ ├── atlas-kg/ # Persistent knowledge graph (cross-session) │ ├── entities.json # Entities with validity windows │ └── triples.json # Subject-predicate-object triples │ ├── atlas-action-graph/ # In-session retrieval log + priority queue │ ├── ${sessionid}.jsonl # Append-only event log │ ├── ${session_id}.state.json # Priority queue (atomic writes) │ └── snapshots/ # PreCompact state-file snapshots │ ├── scripts/ # System utilities │ ├── system-snapshot.js # Writes cache/system-ground-truth.json (drift detector input) │ ├── system-doctor.js # 8-validator scoreboard (skill counts, hooks, commands, …) │ ├── validate-commands.js # Cross-checks commands/ ↔ REFERENCE.md (incl. plugin namespaces) │ ├── validate-{skills,hooks,…}.js # Individual validators consumed by system-doctor │ ├── smoke-test.sh # Quick health probe │ ├── health-validator.js # Drift + health verification │ ├── health-dashboard.js # Metrics surface │ ├── sync-from-local.sh # Local→mirror personal-path scrubber │ └── progressive-learning/ # PreCompact reflection scripts │ └── projects/*/memory/ # Per-CWD auto-memory (user/feedback/project/reference)

## State Management

When resuming, ATLAS reads state in strict precedence order:

| Priority | Source | Purpose |
|:--------:|:-------|:--------|
| 1 | `.flow/state.yaml` | Active Flow workflow state (authoritative) |
| 2 | `~/.claude/handoffs/.md` | Git state + todos from Stop hook (per-CWD — slug replaces `/`, `\`, `:` with `_`) |
| 3 | `~/.claude/atlas-action-graph/${session_id}.state.json` | Previous session's hot-set (48h carryover guard) |
| 4 | `~/.claude/atlas-kg/{entities,triples}.json` | Long-term architectural facts |

---

## MCP Servers

Two registries:

- **`~/.claude.json`** (top-level `mcpServers`) — **USER scope**, global across all CWDs. Managed via `claude mcp add|remove -s user`.
- **`~/.claude/.mcp.json`** — **PROJECT scope**, loaded only when CWD is `~/.claude/`.

Currently ✓ Connected at user scope: `code-review-graph`, `magicuidesign-mcp`, `shadcn`, `prisma`, `tauri-mcp`, `lighthouse`, `heroui`, `context-mode`, `mobile`, `aceternity`, `iconify`, `plugin:firebase:firebase`, and more. Project-scope entries load from `.mcp.json` when CWD=`~/.claude/` and promote to user scope via the `_activate` commands documented in that file.

OAuth-pending (sign-in on first use): `cloudflare`, `linear`, `expo`, `posthog`, `vercel`, `statsig`, `plugin:asana:asana`, `plugin:figma:figma`.

See [`ARCHITECTURE.md`](ARCHITECTURE.md#mcp-servers) for the complete list.

---

## Optional Components

Some hooks reference external components. They degrade gracefully — silent no-op if missing:

| Component | Purpose | How to Get |
|-----------|---------|-----------|
| `cctools-safety-hooks/` | Block dangerous bash commands, file limits, rm enforcement | Install [cctools](https://github.com/anthropics/claude-code-community-tools) |
| `progressive-learning/` | Force reflection before compaction | Ships with ATLAS |
| `claudio` | Audio notifications | Optional binary at `~/.claude/bin/claudio` |
| `code-review-graph` | Tree-sitter code graph (23 languages) | `uvx code-review-graph build` per project |
| `graphify` | Mixed-corpus graph (docs + code + images) | `python -m graphify .` per folder |

---

## What's Novel

| Feature | What It Does | Why It Matters |
|---------|-------------|----------------|
| **Auto-continuation** | Context-aware session chaining with structured handoff | Never lose work mid-task |
| **Complexity scoring** | Automatic agent team deployment | Right-sized execution without asking |
| **Self-evolution** | Creates skills + adds MCP servers on capability gaps | System grows with your needs |
| **Three-layer persistence** | Memory (user) + Knowledge Store (patterns) + Atlas KG (facts) | Strict boundaries, no overlap |
| **Action graph** | In-session retrieval log with priority queue + hot-set carryover | Duplicate-read advisory + PreCompact digest survival |
| **Tier routing** | Haiku/Sonnet/Opus per subtask | Token cost reduction without quality loss |
| **Circuit breaker** | Failure tracking + MCP-aware classification | Prevents runaway tool failures |
| **CRG integration** | Tree-sitter code graph with MCP tool preference | Minimal-context navigation over Glob/Grep |
| **Observability dashboard** (v7.0) | `/observe` renders telemetry from 6 streams | The system shows you what's drifting before you ask |
| **Drift proposer** (v7.0) | SessionStart emits at most 1 advisory per session | Self-surfacing fixes — system proposes, you approve |
| **Unified cleanup engine** (v7.0) | 13 declarative rules in `cleanup-config.json` | One JSONL log per rule, fail-open, 3-line config to add a target |

---

## System Validation

```bash
# Full system smoke test
bash ~/.claude/scripts/smoke-test.sh

# Health dashboard
node ~/.claude/scripts/health-dashboard.js

# Slash command (updates SYSTEM_

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Leo-Atienza](https://github.com/Leo-Atienza)
- **Source:** [Leo-Atienza/atlas-claude](https://github.com/Leo-Atienza/atlas-claude)
- **License:** MIT

Install and usage instructions live in the source repository linked above.