Skip to content
Skills Library
Programming · Research

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.

Repository
codemap ↗
Licence
MIT
Last repository change
06.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 06.09.2026, without references to retired models or APIs.

Licence

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

  1. When to Use This Skill
  2. Quick Reference
  3. Workflow: Finding Code
  4. Symbol Types
  5. Index Structure
  6. Direct JSON Access
  7. Validation
  8. Setup (If Not Initialized)
  9. Best Practices
  10. Example Session
Original SKILL.md headings · 188 lines, 727 words
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

RepositoryScoreLicence
This page · azidan/codemap100MIT
jordancoin/codemap100MIT
AZidan/archflow100MIT
alvinunreal/oh-my-opencode-slim100MIT
jordancoin/codemap100MIT
ils15/copilot-global-config100MIT
ialameh/sift-coder100MIT
jellydn/my-ai-tools96MIT
QDinvest/Code-Map-QD96MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.