🧠 The Problem: The AI Amnesia Trap

AI tools like Claude Code, Cursor, and Copilot let you write code 10x faster. But human cognitive bandwidth hasn't changed.

1. The Illusion of Explanatory Depth : Developers passively read AI-generated code and think "looks good, it compiles", but retain 0% of the mental model.
2. Context Tunneling : LLMs solve local 50-line patches while blindly breaking architectural boundaries and upstream invariants.
3. Blackbox Drift : Large parts of your codebase become unowned "ghost zones" that no human truly understands when production crashes at 3 AM.

✨ The Solution: Real-time Codebase Consciousness

Lucid (CodeAtlas) is a local-first, zero-config toolkit that bridges the cognitive gap :

• 🗺️ Live Mental Map : Generates an interactive visual graph of your architecture, layers, and data flows on localhost:3333.
• ⚡ Live Diff Glow : As Claude or Cursor edits code, impacted upstream callers and downstream dependencies pulse in real-time on your screen.
• 🛡️ AI Amnesia Detector : Automatically identifies untested, undocumented "blackbox" hotspots before they rot into technical debt.
• 🏛️ Socratic Pair Programming : Injects guardrails into Claude Code to force invariant documentation (@invariant) and trade-off justification before code generation.

⚡ Quickstart

Install and initialize in your project in one command :

npx @code-atlas/cli init

This automatically :

1. Parses your codebase AST and builds .code-atlas/map.json.
2. Sets up Socratic .claude/CLAUDE.md directives and /where-am-i, /impact slash commands.
3. Outputs an instant Amnesia Health Report.

Launch the Visual Dashboard

npx @code-atlas/cli ui

👉 Automatically opens http://localhost:3333 with live WebSocket sync!

🧭 Developer Workflow (DX)

1. START DEV        ──► npx @code-atlas/cli ui (opens live map on side screen)
2. PROMPT AI        ──► Claude runs /where-am-i to load invariants & upstream context
3. CO-DESIGN        ──► Claude proposes strategy + trade-offs; developer validates
4. LIVE DIFF GLOW   ──► Modified nodes glow RED; impacted callers highlight in YELLOW
5. COMMIT & PR      ──► npx @code-atlas/cli impact verifies zero broken invariants

🛠️ Claude Code & Agent Slash Commands

| Command | Description | | :--- | :--- | | /where-am-i | Identifies the architectural layer of the current file, its upstream callers, and documented invariants. | | /impact | Calculates the architectural blast radius of uncommitted git changes and warns of high-risk hotspots. | | /grill-me | Challenges the developer on failure modes, concurrency, and edge cases on modified code paths. |

📦 Monorepo Architecture

codeatlas/
├── packages/
│   ├── core/           # AST parser (TypeScript), DAG topology engine, amnesia calculator
│   ├── cli/            # Terminal interface (`init`, `ui`, `impact`, `check`) & WS server
│   ├── web-ui/         # React Flow interactive dark-mode dashboard (Vite + Tailwind)
│   └── claude-plugin/  # Socratic CLAUDE.md directives & slash commands
└── examples/
    └── demo-app/       # Ready-to-run E2E showcase project

🧪 Testing & Verification

# Run unit tests
npm run test

# Build all packages
npm run build

📄 License

MIT © CodeAtlas / Lucid Contributors