🗺️ SourceAtlas

🌐 sourceatlas.io | English | 繁體中文

Get project overview in ~3 minutes by scanning <5% of files

A set of AI-powered slash commands for Claude Code that help you understand any codebase quickly.

---

Have You Ever...

• Spent 3 days on a new project and still don't understand the architecture?
• Wanted to change one line, but afraid it might break everything?
• Asked a colleague "how do I write this", and got "just look at file XXX"?
• Needed to upgrade iOS 16 → 17, but had no idea how much work it would take?

SourceAtlas solves these in minutes, not days.

---

Before & After

Task	Before	After
Understand project architecture	2-3 days	~3-15 minutes ✓
Find API implementation examples	Ask colleagues / random searching	~seconds
Analyze impact of code changes	Manual tracking, hope for the best	~1-2 minutes
Plan framework upgrade	Weeks of research	~15-30 minutes
Find code hotspots & experts	Ask around	~5-10 minutes

_{✓ = benchmarked on 5 open-source projects. Others are estimates based on usage.}

---

How It Works

SourceAtlas uses information theory to prioritize high-entropy files (configs, READMEs, models) over implementation details. By scanning <5% of files, it achieves 70-80% understanding depth in minutes instead of days.

---

Core Commands

1. "I just joined the project, where do I start?"

/sourceatlas:overview

In ~3 minutes, get: Tech stack, architecture patterns, project scale, code quality signals

Example output: Detects Swift 5.10 + MVVM + Coordinator, 12K files, test coverage level

---

2. "I want to write an API, how does this project do it?"

/sourceatlas:pattern "api endpoint"
/sourceatlas:pattern "authentication"
/sourceatlas:pattern "database query"

In 0.1-30 seconds, get: 2-3 best example files with exact line numbers + implementation guide

Example output: Returns UserAPI.swift:45 with matching test file and implementation guide

221 patterns supported: MVVM, Networking, Core Data, React Hooks, Next.js API, Jetpack Compose, Vue Composable, FastAPI, Rails Controller...

---

3. "I want to change this file, what else will break?"

/sourceatlas:impact "src/api/users.ts"
/sourceatlas:impact api "/api/users/{id}"

In 1-2 minutes, get: All dependents, Breaking Change risks, test coverage, migration steps

Example output: Lists 23 dependent files, identifies 5 breaking change risks

---

4. "Who knows this code best? What's the danger zone?"

/sourceatlas:history
/sourceatlas:history src/

In 5-10 minutes, get: Hotspots (files that change constantly), Hidden Coupling, Knowledge Distribution

Example output: Shows PaymentService.swift with 47 changes, flags single-contributor bus factor risk

---

5. "How does the login flow actually work?"

/sourceatlas:flow "user login"
/sourceatlas:flow "checkout process"

In 3-5 minutes, get: Entry points, complete execution path, boundary identification (API/DB/Auth/Payment)

Example output: Traces LoginViewController → AuthService → APIClient → TokenManager

---

6. "We need to upgrade to iOS 17, how much work is that?"

/sourceatlas:deps "iOS 16 → 17"
/sourceatlas:deps "React 17 → 18"
/sourceatlas:deps "Python 3.11 → 3.12"

In 15-30 minutes, get: Deprecated APIs, version checks to remove, third-party compatibility, effort estimate

Example output: Migration checklist with removable version checks, deprecated APIs, effort estimate

---

Benchmark Results

Tested on 5 open-source projects: Firefox iOS, Discourse, Cal.com, Prefect, Thunderbird

Command	Key Metric	Result	Report
overview	Overall Accuracy	93% (56/60)	✓
pattern	Search Precision	98.6% (7/7 cases)	✓
impact	Internal Consistency	100% (5/5 projects)	✓
flow	Entry Point Detection	100% (5/5 projects)	✓
deps	Mode Detection	100% (2/2 cases)	✓
history	Hotspots Detection	100% (Top 10)	✓

_{All E2E verified on 2025-12-21. Languages tested: Swift, Ruby, Python, TypeScript, Kotlin. Click ✓ for detailed reports.}

---

Quick Start (2 minutes)

Requirements

• Claude Code 1.0.33+ (Get it here)
• Git 2.0+
• macOS 12+ or Linux

Installation

Option A: Plugin Marketplace (Recommended)

# In Claude Code:
/plugin marketplace add lis186/SourceAtlas
/plugin install sourceatlas@lis186-SourceAtlas

Option B: Quick Local Testing

git clone https://github.com/lis186/SourceAtlas.git
claude --plugin-dir ./SourceAtlas/plugin

First Use

cd ~/projects/any-project
/sourceatlas:overview  # Start understanding

With Agent Skills, Claude automatically suggests the right analysis based on your questions — no commands to memorize!

---

All 8 Commands

Command	Problem It Solves	Time
/sourceatlas:overview	New to project, need the big picture	~3-15 min ✓
/sourceatlas:pattern "X"	Need to implement X, want examples	~seconds ✓
/sourceatlas:impact "file"	About to change code, worried about side effects	~1-2 min
/sourceatlas:history	Need to find hotspots and experts	~5-10 min
/sourceatlas:flow "feature"	Need to understand a feature's execution path	~3-5 min
/sourceatlas:deps "upgrade"	Planning framework/SDK upgrade	~15-30 min
/sourceatlas:list	Check what analyses are cached	instant
/sourceatlas:clear	Clear outdated cache	instant

_{✓ = benchmarked. Times without ✓ are estimates.}

---

Supported Languages

Language	Patterns	Example Patterns
Swift/iOS	34	MVVM, Coordinator, Core Data, SwiftUI, Combine
TypeScript/React/Vue	50	Hooks, Next.js, Zustand, Pinia, tRPC
Kotlin/Android	31	ViewModel, Room, Compose, Hilt, MVI
Python	26	Django, FastAPI, Flask, Celery, SQLAlchemy
Ruby/Rails	26	ActiveRecord, Controller, Service, Job
Go	26	Handler, Service, Middleware, Repository
Rust	28	Handler, Service, Middleware, Async Runtime

Total: 221 patterns

---

Limitations

Limitation	Details
Benchmark scope	6 commands tested (overview, pattern, flow, impact, deps, history)
Tech Stack detection	May miss secondary languages (e.g., React in a Python project)
Architecture detection	May miss secondary patterns (e.g., MVI in Clean Architecture)
Best for mature projects	Works best with README, config files; limited for undocumented legacy code
Language coverage	7 languages supported; non-mainstream languages need manual verification

---

When NOT to Use

Situation	Why	Alternative
Small projects (<2K LOC)	Reading directly is faster	Just read the code
Need 100% precision	AI has ~93% accuracy	Use static analysis tools
Highly sensitive code	Code sent to Claude API	Check your compliance policy
Offline environment	Requires API connection	Use local tools

---

Privacy & Cost

Aspect	Details
Data Privacy	Code is sent to Claude API for analysis. SourceAtlas itself stores nothing. Check your organization's AI policy.
Token Usage	50-100k tokens per analysis ($0.15-0.30 USD with Sonnet)
Local Processing	Git history analysis (code-maat) runs locally. AST search (ast-grep) runs locally.

---

Save & Share Analyses

All commands support --save:

/sourceatlas:overview --save          # → .sourceatlas/overview.yaml
/sourceatlas:pattern "api" --save     # → .sourceatlas/patterns/api.md
/sourceatlas:history --save           # → .sourceatlas/history.md

Benefits:

• New team members can read existing analyses
• Avoid re-running expensive analyses
• Track how the codebase evolves

Manage cache:

/sourceatlas:list   # View all cached analyses
/sourceatlas:clear  # Clear all or specific caches

---

Documentation

Document	Description
Usage Guide	Complete command reference, all 221 patterns
Case Studies	7 framework analyses (Gin, TCA, FastAPI, tRPC, etc.)
Plugin Guide	Plugin installation and features
Analysis Constitution	Quality principles all analyses follow
CLAUDE.md	Developer guide, architecture

---

Feedback & Contributions

• Report Issues: GitHub Issues
• Contribute Code: PRs welcome

---

Acknowledgments

SourceAtlas is built with these excellent tools:

Tool	Purpose	Link
ast-grep	AST-based code search for pattern and deps commands	GitHub
code-maat	Git history analysis for history command	GitHub
Claude Code	AI-powered code assistant	claude.ai/code

---

SourceAtlas — Understand any codebase in minutes, not days.

v2.10.1 | MIT License | Made with Claude Code