codemap
/codemap
Navigate codebases efficiently using structural indexes. Use when finding symbol definitions (classes, functions, methods), exploring file structure, or locating code by name. Reduces token consumption by 60-80% through targeted line-range reads instead of full file scans.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 06.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Navigate codebases efficiently using structural indexes. Use when finding symbol definitions (classes, functions, methods), exploring file structure, or locating code by name. Reduces token consumption by 60-80% through targeted line-range reads instead of full file scans.
Original author description
Navigate codebases efficiently using structural indexes. Use when finding symbol definitions (classes, functions, methods), exploring file structure, or locating code by name. Reduces token consumption by 60-80% through targeted line-range reads instead of full file scans.
How it works
- When to Use This Skill
- Quick Reference
- Workflow: Finding Code
- Symbol Types
- Index Structure
- Direct JSON Access
- Validation
- Setup (If Not Initialized)
- Best Practices
- Example Session
SKILL.md preview
---
name: codemap
description: Navigate codebases efficiently using structural indexes. Use when finding symbol definitions (classes, functions, methods), exploring file structure, or locating code by name. Reduces token consumption by 60-80% through targeted line-range reads instead of full file scans.
allowed-tools: Read, Bash, Glob, Grep
user-invocable: true
---
# 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
- Navigating YAML config files (keys, sections, nested structures)
- Navigating Markdown docs (sections by H2/H3/H4 headers)
- 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
```bash
# 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 (works with .ts, .yaml, .md, etc.)
codemap show path/to/file.ts
codemap show config.yaml
codemap show docs/README.md
# Check if index is up-to-date
codemap validate
# View index statistics
codemap stats
```
## Workflow: Finding Code
### Step 1: Find Symbol Location
```bash
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
```bash
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 |
| `module` | Ruby module |
| `singleton_method` | Ruby singleton/class method |
| `key` | YAML key/section |
| `section` | Markdown H2 header |
| `subsection` | Markdown H3 header |
| `subsubsection` | Markdown H4 header |
## 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:
```bash
cat .codemap/src/services/.codemap.json
```
## Validation
Before trusting cached line numbers (especially after context compaction):
```bash
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
```bash
# 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"
```bash
# 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
```
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · azidan/codemap | 100 | MIT |
| jordancoin/codemap | 100 | MIT |
| AZidan/archflow | 100 | MIT |
| alvinunreal/oh-my-opencode-slim | 100 | MIT |
| jordancoin/codemap | 100 | MIT |
| ils15/copilot-global-config | 100 | MIT |
| ialameh/sift-coder | 100 | MIT |
| jellydn/my-ai-tools | 96 | MIT |
| QDinvest/Code-Map-QD | 96 | MIT |
Database snapshot: 13.11.2026 · package version 0eadd76e88b5 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100code-map
Build or query a code-only symbol and call-graph map of the current project, via LSP. Use when exploring an unfamiliar codebase, locating a symbol's definition, tracing what calls or is called by a function, assessing the blast radius of a proposed change, or navigating code… - 100codemap-export
Use to export the codemap as machine-readable JSON for downstream tooling. Same data as /codemap, different format. "Export the codemap", "give me the codemap as JSON". - 90rc-codemap
Builds and refreshes per-directory codemap.md as a cheap structure map. Use before exploring a large repo. Do not use to trace one bug. - 100token-optimizer
MANDATORY code inspection and architecture navigation skill. Activate whenever inspecting files, searching code, locating components/functions/classes, reading implementations, analyzing dependencies, or navigating codebase architecture. Replaces wasteful terminal grep/find with… - 100serena-code-nav
Use when navigating code by symbol — finding definitions, all callers, type hierarchies, renaming safely, or editing a method body without reading the whole file. Use instead of Grep for any symbol-level task. - 100tree-sitting
Symbol-level navigation of a local checkout using tree-sitter ASTs. Answers where a symbol is defined, what lines it spans, which symbols a file exposes, what a directory holds, and where a name is referenced — every answer carries exact line ranges to feed straight into a…