Give your AI the map it needs — before it starts writing code.
Index your codebase once. Agents query only what they need.
AI coding agents read your entire codebase on every task. That's expensive, slow, and often inaccurate because context windows fill up before the relevant files are seen. Project Mapper solves this in three steps.
Walk your project once. Extract every module, class, and function via Python AST analysis. No AI required — pure static analysis, zero API cost.
Store entities and their relationships (imports, calls, extends, depends_on) in a local knowledge graph. Subsequent scans only re-process changed files.
Agents call one of 7 MCP tools instead of reading raw files. Context, impact, path, and delta — all answered in milliseconds at a fraction of the token cost.
Returns every entity relevant to a task description. "I'm adding rate limiting to the auth system" → the 20 most relevant files and classes, ranked by relevance.
Traces the dependency graph to find what breaks if you change entity X. Tested on Django's Model class: 69 affected entities found in 11 ms.
Finds the connection chain between two seemingly unrelated entities. Understand hidden coupling before making changes.
Lets agents record what they did to the knowledge graph — keeping the index accurate after code modifications without a full rescan.
Shows what changed on disk since the last scan. Useful for CI pipelines and incremental review workflows.
Starts a background scan from inside a Claude Code or Cursor session — no need to switch to a terminal.
Returns a summary of what's in the database: entity counts by type, files tracked, last scan time, and relation counts.
Tested on the Django source repository (stable/5.1.x · 521,286 lines · 2,918 Python files). All measurements from static analysis only — no AI enrichment, no API keys.
| Test | Metric | Result |
|---|---|---|
| Full cold scan | Entities indexed | 11,988 entities · 34,508 relations |
| Incremental scan (no changes) | Time | 1.88 s (321× faster than full scan) |
| Context query | Latency · Token cost | 79–101 ms · ~1,100–2,000 tokens |
| Same task without PM | Reading 5 relevant files | ~13,000 tokens |
| Impact query on Model | Latency · Affected entities | 11.4 ms · 69 entities found |
| Token reduction | vs. reading files directly | 89–93 % |
Full methodology: django-5-case-study.md ↗
Estimate your monthly savings based on your team size, codebase, and model choice.
The turns / task slider accounts for context accumulation: files loaded in turn 1
stay in the context window for every subsequent turn, so the token cost of not using PM
multiplies with session length. The per-turn reduction percentage stays constant at 89–93 %;
only the absolute dollar cost changes.
Based on the Django 5.x benchmark (89–93% reduction measured from static analysis).
Actual savings vary by codebase and query patterns.
# Install pip install git+https://github.com/Aethvion/Aethvion-ProjectMapper.git # Start the HTTP server uvicorn server:app --port 7474 # Scan your project curl -X POST http://localhost:7474/api/project-mapper/scan \ -H "Content-Type: application/json" \ -d '{"project_root": "/path/to/project", "enrich": false}'
# Clone and run git clone https://github.com/Aethvion/Aethvion-ProjectMapper cd Aethvion-ProjectMapper # Mount your projects directory and start PROJECTS_DIR=/home/you/code docker compose up # Server running at http://localhost:7474/docs
# Add to ~/.claude/settings.json
{
"mcpServers": {
"project-mapper": {
"type": "stdio",
"command": "python",
"args": [
"-m", "project_mapper.mcp_server",
"--db", "my_project",
"--project-root", "/path/to/project"
],
"cwd": "/path/to/Aethvion-ProjectMapper"
}
}
}# Add to .cursor/mcp.json in your project
{
"mcpServers": {
"project-mapper": {
"command": "python",
"args": ["-m", "project_mapper.mcp_server", "--db", "my_project"],
"cwd": "/path/to/Aethvion-ProjectMapper",
"env": { "PM_PROJECT_ROOT": "/path/to/project" }
}
}
}