A deterministic code indexing and retrieval system for AI-assisted development.
CodeAtlas is named after the atlas, a collection of maps. Just as an atlas transforms continents into something that can be explored and understood, CodeAtlas transforms a codebase into a navigable semantic map. Instead of roads and mountains, it charts symbols, and dependencies, their locations, making large repositories easier for both humans and AI to understand.
- 🛠️ Installation
- ✨ Key Benefits
- 📖 What is CodeAtlas?
- ⚙️ How It Works
- 🚀 Why CodeAtlas Matters
- 📊 Benchmarks
- 🔎 First Lookup Accuracy
- 📦 When To Use CodeAtlas
- 🔄 Index Once. Query Many.
- 🏗 Architecture
- 🧭 Design Principles
- ⚡ Quick Start
- 🛣 Roadmap
- 🤝 Contributing
- 📄 License
CodeAtlas requires:
- Go 1.24+
- Universal Ctags https://github.com/universal-ctags/ctags?tab=GPL-2.0-1-ov-file (GPL 2.0)
- jq
- ripgrep / grep (optional)
sudo apt install universal-ctagssudo pacman -S universal-ctagsbrew install universal-ctagsVerify installation:
ctags --versionExpected output should contain:
Universal Ctags
Install the latest release:
curl -fsSL https://raw.githubusercontent.com/Aeres-u99/codeatlas/master/install.sh | bashIf ~/.local/bin is not on your PATH, the installer will tell you how to add it.
Verify the installation:
codeatlas --helpcodeatlas --helpDownload the appropriate binary from the GitHub Releases page.
Rename it to codeatlas, make it executable, and place it somewhere on your PATH:
chmod +x codeatlas-linux-amd64
mv codeatlas-linux-amd64 codeatlas
sudo mv codeatlas /usr/local/bin/Verify:
codeatlas --helpRun the installer again or Download manually and install:
curl -fsSL https://raw.githubusercontent.com/Aeres-u99/codeatlas/master/install.sh | bashgit clone https://github.com/Aeres-u99/codeatlas.git
cd codeatlas
makeThis is pending, but we do plan to add tests. Sadly this wasn't made using TDD
make testCodeAtlas uses CGo (via Tree-sitter), so cross-compilation requires a C cross-compiler for the target architecture — GOARCH alone is not enough.
Install the cross-compiler:
sudo apt install gcc-aarch64-linux-gnusudo pacman -S aarch64-linux-gnu-gccBuild:
make build-linux-arm64Output: dist/codeatlas-linux-arm64
Transfer the binary to your ARM machine and install:
scp dist/codeatlas-linux-arm64 user@arm-host:~
ssh user@arm-host 'sudo install ~/codeatlas-linux-arm64 /usr/local/bin/codeatlas'make build-linux-amd64Output: dist/codeatlas-linux-amd64
Darwin cross-compilation from Linux requires the macOS SDK and is not supported here. Run these on the Mac itself.
make build-darwin-arm64Output: dist/codeatlas-darwin-arm64
make build-darwin-amd64Output: dist/codeatlas-darwin-amd64
make build-allProduces both dist/codeatlas-linux-amd64 and dist/codeatlas-linux-arm64.
sudo install codeatlas /usr/local/bin/codeatlasVerify installation:
codeatlas --help| 🎯 Direct Navigation | ⚡ High Efficiency | 💰 Lower Cost | 🔍 Works at Scale |
|---|---|---|---|
| Jump directly to implementations without exploring the repository tree. | Reduce repository exploration through targeted symbol retrieval. | Fewer searches, fewer tool calls, lower latency. | Designed for medium and large repositories. |
CodeAtlas is a repository indexing and retrieval system that produces a structured symbol index (codeatlas.json) of your codebase.
You can then query this index using simple tools such as:
- grep
- jq
- ripgrep
- Claude Code
- Aider
- Custom agents
Instead of feeding your entire repository to an LLM, CodeAtlas retrieves only the relevant functions, types, files, and locations.
Repository
│
▼
CodeAtlas Index
│
▼
grep / jq / rg
│
▼
Relevant Symbols
│
▼
LLM
CodeAtlas parses the repository using Tree-sitter and extracts:
- Functions
- Methods
- Structs
- Interfaces
- Constants
- Variables
- Imports
- File Locations
codeatlas -input .Output:
codeatlas.json
Search for symbols using standard UNIX tools.
grep -C3 "ConfigureProvider" codeatlas.jsonor
jq '.idx["ConfigureProvider"]' codeatlas.jsonOpen the exact files and locations returned by CodeAtlas.
No blind repository exploration required.
CodeAtlas supports a .codeatlasignore file to exclude files and directories that provide little or no value for code navigation.
Ignoring generated code, vendored dependencies, documentation, test fixtures, repository metadata, and build artifacts can significantly reduce index size, indexing time, and query noise.
A well-tuned .codeatlasignore helps CodeAtlas focus on implementation code rather than auxiliary repository content.
# Repository metadata
.git/**
.github/**
# Dependencies
vendor/
node_modules/
# Documentation
docs/
*.md
# Generated files
**/zz_generated.*
**/*_generated.go
# Test fixtures
**/testdata/
**/*_test.go
# Build artifacts
dist/
build/
tmp/
# IDE files
.idea/
.vscode/- ⚡ Faster indexing
- 📉 Smaller index size
- 🎯 Better retrieval precision
- 💰 Lower token consumption
- 🔍 Reduced search noise
CodeAtlas is designed around the principle that not all repository content is equally valuable for navigation. A carefully curated .codeatlasignore allows the index to focus on the code that matters most.
Tip: For large repositories such as Kubernetes, Loki, or Terraform, excluding
.git/**, vendored dependencies, generated files, and documentation can dramatically reduce index size while preserving the vast majority of implementation-relevant symbols.
Modern LLM workflows spend the majority of their time and tokens exploring repositories.
Typical workflow:
Search
↓
Open File
↓
Wrong File
↓
Search Again
↓
Open More Files
↓
Find Implementation
CodeAtlas transforms that into:
Lookup Symbol
↓
Open Correct File
↓
Done
Benefits:
- Fewer file reads
- Lower token usage
- Fewer tool calls
- Faster navigation
- Lower latency
- Better agent performance
codeatlas -input .This generates:
codeatlas.json
which can then be queried using:
jq -r '.idx | keys[]' codeatlas.jsonor
jq -r '.idx["main.main"]' codeatlas.jsonCodeAtlas has been benchmarked against three real-world repositories of different scales.
| Repository | Files | LOC | Runtime (s) | Full Map Tokens | Query Tokens | Retrieval Reduction |
|---|---|---|---|---|---|---|
| Kubernetes | 30,536 | 5.0M | 66.2 | 14.7M | 2,059 | 99.986% |
| Loki | 17,160 | 510k | 11.6 | 8.4M | 880 | 99.990% |
| Terraform | 5,411 | 667k | 13.8 | 2.0M | 5,340 | 99.732% |
| Repository | Exploration Collapse | Cost Reduction |
|---|---|---|
| Kubernetes | 60.0% | 49.6% |
| Loki | 50.0% | 50.2% |
| Terraform | 62.5% | 7.2% |
CodeAtlas is a retrieval system, not a context-stuffing system.
| Repository | Full Map Tokens | Query Tokens |
|---|---|---|
| Kubernetes | 14,718,000 | 2,059 |
| Loki | 8,396,000 | 880 |
| Terraform | 1,990,000 | 5,340 |
CodeAtlas consistently reduces retrieval payloads by over 99.7%.
The entire repository is never sent to the model.
Only the relevant symbols are retrieved.
| Repository | First Lookup Correct |
|---|---|
| Kubernetes | ✅ Yes |
| Loki | ✅ Yes |
| Terraform | ❌ Required Refinement |
CodeAtlas performs best when queried using specific symbols.
Broad interfaces and common method names may require one or more refinement steps.
CodeAtlas is optimized for medium and large repositories.
| Repository Size | Expected Benefit | Recommendation |
|---|---|---|
| < 100 files | Low | Generally not recommended |
| 100 – 1,000 files | Medium | Situational benefit |
| 1,000 – 10,000 files | High | Strong benefit |
| 10,000+ files | Very High | Primary target |
Smaller repositories may not see enough benefit to offset indexing overhead.
Index generation is a one-time operation.
The resulting index can be reused across:
- Feature development
- Bug investigation
- Architecture discovery
- Code reviews
- AI-assisted programming
- Documentation generation
Repository
│
▼
Generate Index
│
▼
codeatlas.json
│
├── Query #1
├── Query #2
├── Query #3
├── Query #4
└── Query #N
The generation cost is paid once. Or, if post Query #1 the syntax or structure has changed significantly, regenerate the codeatlas.json to ensure that the map is not stale.
The retrieval benefit compounds over time.
Repository
│
▼
Tree-sitter Parser
│
▼
CodeAtlas Index
│
├── Functions
├── Methods
├── Structs
├── Interfaces
├── Variables
├── Constants
└── Imports
│
▼
grep / jq / rg
│
▼
LLM / Agent
Never send the entire repository to the model.
Retrieve only the relevant implementation details.
Same repository → same index.
No embeddings.
No probabilistic ranking.
Indexes are human-readable and versionable.
You can inspect, diff, and audit every result.
Works with standard UNIX tooling:
- grep
- jq
- rg
- awk
- sed
Built on Tree-sitter.
Designed to understand source structure rather than plain text.
CodeAtlas Help
❯ codeatlas --help
codeatlas - The Code Map you will Ever need!
For custom CTAGS path use Environment Variable CODEATLAS_CTAGS for custom path
-input string
Code to Parse (default "code.py")
-output string
Code to Parse (default "codeatlas.json")
Have Fun
Generate an index:
codeatlas -input .Search for a symbol:
grep -C3 "MyFunction" codeatlas.jsonRetrieve with jq:
jq '.idx["MyFunction"]' codeatlas.jsonOpen the returned file and line.
Done.
- TODO
- Incremental indexing
- Multi-language support
- Cross-reference graph
Contributions, bug reports, and feature requests are welcome.
Please open an issue or submit a pull request.
MIT