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
archflow ↗
Licence
MIT
Last repository change
27.10.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 27.10.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 · 179 lines, 657 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
- 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

# 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
```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 |

## 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)
# Pinned to the v1.3.1 release on purpose — see SECURITY.md. Never use a branch here.
pip install "git+https://github.com/AZidan/codemap.git@v1.3.1"

# Initialize index
codemap init .
```

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

### Start Watch Mode (Recommended)
Start watch mode in the background to keep the index automatically updated:
```bash
codemap watch . &
```

This runs in the background and updates the index whenever files change. No need to manually run `codemap update`.

To stop watch mode later:
```bash
pkill -f "codemap watch"
```

## Best Practices

1. **Search before scanning**: Always try `codemap find` before grep/glob
2. **Use line ranges**: Read specific line ranges instead of full files
3. **Check freshness**: Use `codemap validate` before trusting cached line numbers
4. **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
```

Versions

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

Database snapshot: 13.11.2026 · package version 15af954f7e98 (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

  • 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.
  • 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…
  • 95codebase-search
    Search and navigate large codebases efficiently. Use when finding specific code patterns, tracing function calls, understanding code structure, or locating bugs. Handles semantic search, grep patterns, AST analysis.
  • 100codemap-refresh
    Use when code has changed since codemap files were generated and the user wants them brought up to date: "refresh", "update the diagrams", "docs are stale". Detects which docs/codemap files are outdated and regenerates only those, preserving manual edits.
  • 90explore
    Systematic codebase exploration using codemap's analysis tools. Use when understanding how code works, tracing dependencies, or onboarding to a new area.

Feedback and reports

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