codemap

CodeMap - Codebase Structural Index

Navigate codebases efficiently using pre-built structural indexes stored in .codemap/ directories.

When to Use This Skill

USE CodeMap when:

• Finding where a class, function, method, or type is defined
• Understanding a file's structure before reading it
• Searching for symbols by name
• Reducing token usage during codebase exploration

READ full files when:

• Understanding implementation details
• Making edits to code
• The symbol isn't in the index (new/untracked file)

Quick Reference

# Find a symbol by name (case-insensitive)
codemap find "SymbolName"

# Filter by type
codemap find "handle" --type method
codemap find "User" --type class
codemap find "Config" --type interface

# Fuzzy search (word matching, typo tolerance, docstring search)
codemap find "user service" --fuzzy
codemap find "pricng" --fuzzy           # Handles typos

# Show file structure with all symbols
codemap show path/to/file.ts

# Check if index is up-to-date
codemap validate

# View index statistics
codemap stats

Workflow: Finding Code

Step 1: Find Symbol Location

codemap find "UserService"

Output:

src/services/user.ts:15-189 [class] UserService
  (config: Config)

Step 2: Read Only Relevant Lines

Instead of reading the entire file, read just lines 15-189:

Read src/services/user.ts lines 15-189

Step 3: Explore Nested Symbols

codemap show src/services/user.ts

Output:

File: src/services/user.ts (hash: a3f2b8c1)
Lines: 542
Language: typescript

Symbols:
- UserService [class] L15-189
  - constructor [method] L20-35
  - getUser [method] L37-98
    (userId: string) : Promise<User>
  - createUser [async_method] L100-145
    (data: CreateUserDto) : Promise<User>

Symbol Types

Type	Description
class	Class declaration
function	Function declaration
method	Class method
async_function	Async function
async_method	Async class method
interface	TypeScript interface
type	TypeScript type alias
enum	Enum declaration

Index Structure

The .codemap/ directory mirrors the project structure:

.codemap/
├── .codemap.json              # Root manifest
├── _root.codemap.json         # Files in project root
├── src/
│   ├── .codemap.json          # Files in src/
│   └── services/
│       └── .codemap.json      # Files in src/services/

Direct JSON Access

For programmatic access, read the JSON files directly:

cat .codemap/src/services/.codemap.json

Validation

Before trusting cached line numbers (especially after context compaction):

codemap validate path/to/file.ts

• "up to date": Line ranges are valid
• "stale": File changed, re-read or run codemap update

Setup (If Not Initialized)

If a project doesn't have a .codemap/ directory:

Prerequisites

• Python 3.10+ and pip must be installed
• Verify with: python3 --version && pip --version

Installation

# Install codemap from GitHub (NOT from PyPI - there's a different package there)
pip install git+https://github.com/AZidan/codemap.git

# Initialize index
codemap init .

# Optional: Install git hooks for auto-updates
codemap install-hooks

IMPORTANT: Do NOT use pip install codemap - that installs a different package from PyPI. Always use the GitHub URL above.

Best Practices

1. Search before scanning: Always try codemap find before grep/glob
2. Use --fuzzy when exact search fails: If codemap find returns nothing, retry with --fuzzy for broader matching
3. Use line ranges: Read specific line ranges instead of full files
4. Check freshness: Use codemap validate before trusting cached line numbers
5. Explore structure first: Use codemap show to understand file layout before diving in

Example Session

Task: "Fix the authentication bug in the login handler"

# 1. Find relevant symbols
codemap find "login"
# → src/auth/handlers.ts:45-92 [function] handleLogin

# 2. Check file structure
codemap show src/auth/handlers.ts
# Shows handleLogin and related functions with line ranges

# 3. Read only the relevant function (lines 45-92)
# ... make your fix ...

# 4. If you need related code, find it
codemap find "validateToken"
# → src/auth/utils.ts:12-38 [function] validateToken

# 5. If exact search misses, try fuzzy
codemap find "auth middleware" --fuzzy
# → src/auth/middleware.ts [file]
# → src/auth/handlers.ts:10-25 [function] authenticateRequest