MacroManAtlas

Automatic codebase indexer for Claude Code -- keep your AI pair-programmer oriented in any project, across every session.

What It Does

• Scans your repository and discovers modules, packages, and top-level directories automatically based on project type (CMake, Cargo, Go modules, Node workspaces, and more).
• Generates per-module READMEs with file listings, tags, descriptions, dependencies, and public API summaries so Claude always knows what lives where.
• Injects a compact summary (index.summary.md, <4 KB) into Claude's context at session start -- no manual copy-paste required.
• Auto-syncs the index in the background whenever you create or edit files, using a debounced claude -p daemon with module-level locking.
• Survives context compaction by re-injecting the summary before the context window is compressed, so Claude never loses the map.

Supported Project Types

Priority	Type	Detection Signal
1	C/C++ CMake	CMakeLists.txt
2	Rust Cargo	Cargo.toml
3	Go	go.mod
4	Node.js / TypeScript	package.json (workspaces)
5	.NET	*.sln or *.csproj
6	Java Maven	pom.xml
7	Java Gradle	build.gradle / build.gradle.kts
8	Python	pyproject.toml, setup.py, or setup.cfg
9	Dart / Flutter	pubspec.yaml
10	Generic fallback	Any directory structure

See docs/SUPPORTED-PROJECTS.md for full detection and extraction details.

Installation

# Add the marketplace
claude plugin marketplace add MacroMan5/macromanatlas

# Install the plugin
claude plugin install macromanatlas@macromanatlas-marketplace

Or use the interactive TUI: /plugin marketplace add MacroMan5/macromanatlas

Usage

Initialize the index

/index-init

Scans the repository, generates per-module READMEs, creates .claude/index.md and .claude/index.summary.md, and registers hooks for auto-sync.

To add the index files to .gitignore (recommended for private/personal indexes):

/index-init --gitignore

Check index status

/index-status

Shows which modules are indexed, last sync time, and any stale or missing entries.

Rebuild the index

# Full rebuild
/index-rebuild

# Rebuild a specific module
/index-rebuild --module MacroMan-Core

# Rebuild with custom instructions
/index-rebuild --m "Focus on public interfaces and skip test files"

How It Works

MacroManAtlas uses four Claude Code hooks to maintain the index lifecycle:

Hook	Trigger	Action
SessionStart	Session start, resume, clear, compact	Injects index.summary.md (<4 KB) into context
PostToolUse	Write or Edit tool calls	Spawns background daemon to sync affected module
PreCompact	Before context compression	Re-injects summary so the map survives compaction
Stop	Session end	Warns about unsynced file changes

The background sync daemon uses flock for per-module concurrency control and a 30-second debounce to avoid redundant updates. See docs/HOW-IT-WORKS.md for the full architecture.

Example Output

.claude/index.summary.md (injected into context)

# Project Index — MyApp

Type: cpp-cmake | Modules: 6 | Files: 142 | Updated: 2026-02-13T10:30:00Z

## Modules
| Module | Purpose | Key Files |
|--------|---------|-----------|
| Core | Interfaces and shared types | IDetector.h, IMouseDriver.h |
| Detection | ONNX/TensorRT inference | OrtDetector.cpp, PostProcessor.cpp |
| Tracking | Target selection and prediction | StickyAimTracker.cpp, KalmanPredictor.cpp |
...

Per-module README.md

<!-- AUTO-GENERATED by MacroManAtlas -- do not edit above this line -->
# Core

Interfaces and shared types for the pipeline.

## Files
| File | Tags | Description |
|------|------|-------------|
| include/interfaces/IDetector.h | interface, detection | Abstract detector interface |
| include/entities/Detection.h | entity, detection | Bounding-box detection struct |
...

## Dependencies
- Eigen 3.4
- spdlog

## Public API
- `IDetector` -- abstract detection interface
- `IScreenCapture` -- abstract capture interface
<!-- AUTO-GENERATED end -->

<!-- CUSTOM -->
These interfaces are stable. Breaking changes require a migration note.
<!-- /CUSTOM -->

Requirements

Dependency	Purpose	Install
bash	Shell scripts	Pre-installed on macOS/Linux
jq	JSON parsing in hooks	brew install jq / apt install jq
flock	Concurrency control	apt install util-linux (Linux); macOS: brew install flock

Windows users: Requires WSL, Git Bash (MSYS2), or equivalent POSIX-compatible shell. See docs/USAGE.md for setup instructions.

Configuration

No configuration files needed. MacroManAtlas works out of the box after /index-init.

• Use --gitignore with /index-init to keep index files out of version control.
• Use --m "instructions" with /index-rebuild to guide the AI during regeneration.
• Add persistent notes in the <!-- CUSTOM --> section of any module README -- these are preserved across rebuilds.

Documentation

• Usage Guide -- installation, commands, troubleshooting
• How It Works -- architecture, hooks, daemon, security
• Supported Projects -- detection and extraction per project type
• Contributing -- adding detectors, reporting bugs, development setup

License

MIT