ai-code-atlas

v0.1.1

Published

7 days ago

Smart codebase architectural map generator for AI coding agents. Compress repos by 95%+ into high-density semantic context.

0High
0Medium
0Low

hasanacar

ai agent llm codebase repo-map context cursor claude copilot mcp developer-tools ast architecture

🧭 Code Atlas (`ai-code-atlas`)

Smart Codebase Architectural Map Generator for AI Coding Agents.
Compress entire repositories by 90–95%+ into high-density semantic maps. Give Cursor, Claude Code, Windsurf, Copilot, and Aider surgical precision without burning your token budget.

🎯 The Problem

When you prompt an AI coding agent (Cursor, Claude Code, Windsurf, Copilot, Devin):

"Update the discount coupon calculation rule in the checkout flow"

The agent typically:

Blindly greps or opens 30+ files, ingesting node_modules, database models, tests, and irrelevant utilities.
Burns 50,000 to 200,000+ tokens just trying to locate where the logic lives.
Suffers from "Lost-in-the-Middle" context degradation, hallucinating variable names or modifying the wrong service.

⚡ The Solution: `ai-code-atlas`

ai-code-atlas crawls your repository, parses the AST, and builds an ultra-compact Architectural Map (AGENT_MAP.md) in milliseconds:

✂️ AST Signatures Without Bloat: Strips out function and class bodies ({ ... }), preserving only export names, parameter types, return signatures, interfaces, and struct definitions.
🎯 Task Focus Pinpointing: Run npx ai-code-atlas --focus "coupon discount" to instantly highlight the exact 2 or 3 target files the agent needs to touch.
🏗️ Architectural Layer Tagging: Automatically categorizes files into [API & Entrypoints], [Services & Business Logic], [Data & Models], [Utils], and [Config].
📊 Mermaid Flowchart Generation: Run with --diagram to generate visual architecture flowcharts.
🎯 Token Budget Capping: Run with --budget 10000 or --compact for massive monorepos to guarantee it fits your LLM context window.
🌐 Polyglot Multi-Language Support: First-class AST parsing for TypeScript, JavaScript (ESM & CommonJS), Python, Go, and Java.
📉 90–95%+ Token Reduction: Shrinks a 60,000-token codebase into ~1,000 tokens of high-density briefing.

📊 How Does `ai-code-atlas` Compare?

🏆 Real-World Benchmarks (Famous Open-Source Repos)

Real-world performance tested on iconic open-source repositories:

| Repository | Primary Stack | Files / Lines | Original Tokens | Atlas Map Tokens | Token Savings | Analysis Time | | :--- | :--- | :--- | :--- | :--- | :---: | :---: | | Express.js | JavaScript | 149 files / 22,217 lines | ~141,687 | ~4,047 | 97.1% 🚀 | 204 ms | | Gin Web Framework | Go | 110 files / 25,141 lines | ~179,538 | ~7,324 | 95.9% 🚀 | 139 ms | | Flask | Python | 101 files / 19,117 lines | ~151,866 | ~5,539 | 96.4% 🚀 | 75 ms | | Zustand | TypeScript | 70 files / 10,751 lines | ~79,197 | ~2,834 | 96.4% 🚀 | 139 ms | | FastAPI | Python | 1,219 files / 127,925 lines | ~1,116,339 | ~70,856 | 93.7% 🚀 | 191 ms |

Tested on an Apple Silicon machine. All benchmarks executed with zero warmup and default settings.

🚀 Quickstart

Run directly in any project root with npx (no install required):

# Generate AGENT_MAP.md in the current directory
npx ai-code-atlas

🎯 1. Task Pinpointer Mode (Recommended for AI Prompts)

When you're about to ask an AI agent to solve a specific task, run:

npx ai-code-atlas --focus "client login jwt token"

This places a prominent 🎯 Task Focus Targets section at the very top of the map, pinpointing the exact target files and symbols responsible for that feature.

⚡ 2. Compact High-Density Mode

For larger projects where you want single-line file summaries:

npx ai-code-atlas --compact

📊 3. Visual Architecture Diagram

Generate an interactive Mermaid diagram inside your map:

npx ai-code-atlas --diagram

💰 4. Token Budget Cap (For Large Repos & Monorepos)

Guarantee your map never exceeds a given token limit:

npx ai-code-atlas --budget 8000

📋 Example Generated Map

# 🧭 Code Atlas: Architectural Map for AI Agents

> 📊 Original Codebase: ~58,096 tokens (143 files, 9,705 lines)
> ⚡ Atlas Map: ~4,454 tokens (92.3% token reduction)
> 🏷️ Primary Stack: JavaScript / Node.js

---

## 🎯 Task Focus Targets (Query: "client login jwt token")
> The AI Agent should prioritize inspecting and editing these target files first:

### `src/services/user/jwt-token.js` (Score: 85, 20 lines)
- 💡 Relevance: Path contains "jwt"; Symbol `generateJWToken` matches "jwt"
- Key Symbols:
  - `generateJWToken(user)`
  - `generateJWTokenForClient(client)`
- 🔗 Dependencies: `jsonwebtoken`

### `src/models/client-login-fail.js` (Score: 74, 48 lines)
- 💡 Relevance: Path contains "client"; Path contains "login"
- Key Symbols:
  - `ClientLoginFails(sequelize, DataTypes)`
- 🔗 Dependencies: `sequelize`

---

## 🗺️ Architectural Layer Map

### 🌐 API & Entrypoints (39 files)
- **`src/controller/client/auth.js`** (118 lines)
  - 🧩 *Exports:* `login(req, res, next)`, `register(...)`, `search(...)`, `session(...)`
  - 🔗 *Uses:* `../../services/client/auth, ../../services/user/jwt-token, http-errors`

### ⚙️ Business Logic & Services (12 files)
- **`src/services/project/index.js`** (228 lines)
  - 🧩 *Exports:* `create(...)`, `retrieve(...)`, `adminSearch(...)`
  - 🔗 *Uses:* `../../models, sequelize`

### 💾 Data, Models & Schemas (47 files)
- **`src/models/client.js`** (83 lines)
  - 🧩 *Exports:* `class Client { associate(models) }`
  - 🔗 *Uses:* `bcrypt, sequelize`

💡 How to Integrate with AI Coding Assistants

1. In Cursor (`.cursorrules`)

Add this line to your project's .cursorrules:

Before modifying code or inspecting modules, always read `AGENT_MAP.md` to locate the exact layers, exported symbols, and target files.

2. In Claude Code (`CLAUDE.md`)

Add this to your project's CLAUDE.md:

# Codebase Orientation
Refer to `AGENT_MAP.md` for the architectural structure and module symbols.
To refresh the map for a task: `npx ai-code-atlas --focus "<task>"`

3. In Windsurf (`.windsurfrules`)

Check `AGENT_MAP.md` before navigating the codebase to minimize token usage and identify relevant service exports.

4. Direct Terminal Pipe

Copy the focused map directly to your clipboard:

# macOS
npx ai-code-atlas --focus "checkout payment" --stdout | pbcopy

# Linux
npx ai-code-atlas --focus "checkout payment" --stdout | xclip -selection clipboard

🛠️ CLI Options

💻 Programmatic SDK Usage

You can also use ai-code-atlas inside your own Node.js / TypeScript scripts or tools:

import { generateAtlas } from 'ai-code-atlas';

const { map, output, focusMatches } = generateAtlas({
  cwd: './my-project',
  focus: 'payment webhook',
  compact: true,
  diagram: true
});

console.log(`Original: ~${map.originalTokens} tokens`);
console.log(`Atlas Map: ~${map.mapTokens} tokens`);
console.log(`Compression: ${(map.compressionRatio * 100).toFixed(1)}% reduction!`);

🌐 Supported Languages & AST Parsers

TypeScript (.ts, .tsx) — Full AST via official TypeScript Compiler API.
JavaScript (.js, .jsx, .mjs, .cjs) — ESM and CommonJS (module.exports, exports, require).
Python (.py) — Classes, def functions, type hints, docstrings, and imports.
Go (.go) — Packages, structs, interfaces, methods, functions, and imports.
Java (.java) — Classes, records, interfaces, method signatures, and imports.

⚡ Standalone Native Binary (No Node.js Required)

Don't want to install Node.js or run npm? We provide a zero-dependency standalone Go CLI in extras/go-cli:

Zero dependencies: Built 100% on the Go standard library.
Single binary: Fast static executable (~3MB) for macOS, Linux, and Windows.
Cross-platform: Build in seconds with go build or use ./build.sh.

# Compile and run anywhere:
cd extras/go-cli
go build -o code-atlas main.go
./code-atlas /path/to/any/repo

See the Go CLI Documentation for full options.

🤝 Contributing

Contributions, feedback, and parser extensions (Rust, C#, PHP, Ruby, etc.) are warmly welcome!
Please see CONTRIBUTING.md for local development guidelines.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

🧭 Code Atlas (ai-code-atlas)