codemap

---

The Problem

LLMs explore codebases iteratively. They:

1. Think about what they need
2. Read some code
3. Think again
4. Read more code
5. Repeat

The problem is that reading code is expensive.

Without help, an LLM often has to:

• Read entire files
• Re-read the same files after context resets
• Pull in large chunks "just in case"

This quickly leads to massive token usage—even when the LLM only needed a small part of each file.

---

The Insight

LLMs don't need less reasoning. They need cheaper reads.

If you make each "read code" step smaller and more precise, the same reasoning process becomes dramatically cheaper.

The bottleneck is not intelligence — it's I/O cost.

That's what CodeMap fixes.

---

What CodeMap Is (and Is Not)

✅ What CodeMap is

• A structural index of your codebase
• A fast way to locate symbols and their exact line ranges
• A tool that lets an LLM jump directly to relevant snippets
• A cost-reduction layer for iterative LLM reasoning

❌ What CodeMap is not

• Not a semantic analyzer
• Not an architecture inference engine
• Not a replacement for LSPs
• Not an agent
• Not "smart"

CodeMap does not decide what code matters. It only makes it cheaper to read the code the LLM decides to look at.

---

How This Changes LLM Code Exploration

Without CodeMap

LLM thinks
  → reads 5 full files (~30K tokens)
  → thinks
  → reads 3 more full files (~18K tokens)

Total: ~48K tokens

With CodeMap

LLM thinks
  → queries symbols → reads 5 targeted snippets (~5K tokens)
  → thinks
  → queries again → reads 3 more snippets (~3K tokens)

Total: ~8K tokens

Same reasoning. Same conclusions. ~83% fewer tokens.

The LLM can always escalate: snippet → larger slice → full file. CodeMap never blocks access—it just makes precision cheap.

---

📊 Measured Impact

The savings compound across a session:

Scenario	Without CodeMap	With CodeMap	Savings
Single class lookup	1,700 tokens	1,000 tokens	41%
10-file refactor	51,000 tokens	11,600 tokens	77%
50-turn coding session	70,000 tokens	21,000 tokens	70%

It's not about any single lookup. It's about making every lookup cheaper and letting those savings multiply.

---

⚡ Quick Start

Install via pip or uv

pip install git+https://github.com/AZidan/codemap.git
uv tool install codemap --from https://github.com/AZidan/codemap.git

Use

codemap init .
codemap watch . &   # Keep index updated in background
codemap find "ClassName"
# → src/file.py:15-89 [class] ClassName

# Now the LLM reads only lines 15-89 instead of the entire file

---

How It Works

1. CodeMap scans your repository and builds a symbol index
2. Each symbol is mapped to:
   • File path
   • Start line / end line
   • Type (function, class, method, etc.)
   • Signature and docstring (optional)
3. The index is stored locally under .codemap/
4. An LLM (or human) can:
   • Search for symbols by name
   • Read only the exact lines needed
   • Check if files changed without re-reading them
   • Repeat as part of its reasoning loop

No embeddings. No inference. No opinions.

---

Commands

codemap init [PATH]

Build the index for a directory.

codemap init                     # Index current directory
codemap init ./src               # Index specific directory
codemap init -l python           # Only Python files
codemap init -e "**/tests/**"    # Exclude patterns

codemap find QUERY

Find symbols by name (case-insensitive substring match).

codemap find "UserService"              # Find by name
codemap find "process" --type method    # Filter by type
codemap find "handle" --type function   # Functions only

Output:

src/services/user.py:15-89 [class] UserService
src/services/user.py:20-45 [method] process_request

Fuzzy Search