Skip to main content
skill CX Codex

map · sethgammon — Claude Code skill: codebase index, how to install

map generates a JSON index of a repository's files, exports, imports and dependency graph so an agent can locate relevant code without extra Glob or Grep calls.

MIT ★ 937 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local
Open on GitHub

What map does

The skill runs node scripts/map-index.js --generate --root ., walking the project tree while honoring .gitignore and skipping folders like node_modules and dist. For each source file it pulls out exports, imports and symbols, assigns a role such as component, hook, store, route, test or config, and links files into a dependency graph based on resolved import paths. The result is written to .planning/map/index.json, with per-file SHA-256 hashes letting /map stale detect what changed since the last run.

Indexing covers TypeScript, JavaScript, Python, Go and Rust. A fresh index is cached for five minutes, so repeated runs inside that window exit immediately unless called with --force.

The /map slice command builds a keyword-scoped block capped at 8000 characters for safe injection into another agent's prompt. In Fleet-driven runs, this slice is attached automatically to each spawned agent next to CLAUDE.md whenever an index already exists for the project.

What it helps with

  • locate files by keyword without reading the whole repo
  • map dependencies between modules before a refactor
  • hand Fleet agents a scoped context slice instead of a full directory scan
  • detect whether the index went stale after edits
  • get a quick breakdown of languages, roles and route counts

Example prompts for the agent

  • Run /map to build the codebase index
  • Use /map query auth to find files tied to authentication
  • Check /map stale before starting a long campaign

How to install map

1Plugin marketplace

/plugin marketplace add SethGammon/Citadel
/plugin install citadel@citadel-local

This installs the whole citadel plugin with all its skills

2Skills CLI (Vercel)

npx skills add SethGammon/Citadel --skill map -a claude-code

3Manually: put the files in place

~/.claude/skills/map/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/map/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about map

How do I install map in Claude Code?

Run /plugin marketplace add SethGammon/Citadel, then /plugin install citadel@citadel-local.

What does the map skill do?

It builds a JSON index of a project's files, exports, imports, dependency graph and file roles, searchable by keyword. The same index feeds compact context slices handed to other agents.

Which languages does map support?

TypeScript, JavaScript, Python, Go and Rust.

Source text

SKILL.md · MIT
---
name: map
license: MIT
description: >-
  Structural codebase index generator. Builds a compact JSON map of files,
  exports, imports, dependency graph, and roles. Queryable by keyword. Injected
  into fleet agents as context slices to reduce token usage on code navigation.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - map
  - index codebase
  - codebase map
  - structural index
  - scan codebase
  - map stats
  - map query
last-updated: 2026-03-29
---

# /map -- Codebase Intelligence

## Orientation

Use `/map` when:
- Starting work on an unfamiliar codebase (build the index first)
- A fleet or archon campaign needs agents to know "what files matter for X"
- You want a quick structural overview (stats, roles, dependency graph)
- You need to find files related to a keyword without exploratory reads

Do not use `/map` for:
- Reading file contents (use Read)
- Searching for string patterns inside files (use Grep)
- Single-file edits where you already know the path

## Commands

| Command | Behavior |
|---|---|
| `/map` | Generate or refresh the index (skips if cache is fresh) |
| `/map --force` | Rebuild the index even if cache is fresh |
| `/map query <terms>` | Search the index for files matching keywords |
| `/map stats` | Print summary statistics (files, lines, languages, roles) |
| `/map slice <terms>` | Output a compact context slice for agent injection |
| `/map stale` | Detect added, changed, or removed indexed source files |

## Protocol

### Step 1: GENERATE INDEX

Run the index generator:

```bash
node scripts/map-index.js --generate --root .
```

Add `--force` if the user requested a fresh rebuild or if the index is stale.

The generator:
1. Walks the project tree (respects `.gitignore`, skips `node_modules`, `dist`, etc.)
2. Extracts exports, imports, and symbols from each source file
3. Infers a role for each file (component, hook, store, route, test, config, etc.)
4. Builds a dependency graph from resolved import paths
5. Records per-file SHA-256 hashes plus a whole-index source signature
6. Extracts route-like paths and package verification scripts
7. Writes the index to `.planning/map/index.json`

**Supported languages:** TypeScript, JavaScript, Python, Go, Rust.

**Cache behavior:** The index is cached for 5 minutes. Subsequent runs within
that window exit immediately unless `--force` is passed.

If `.planning/map/` does not exist, the generator creates it automatically.

### Step 2: QUERY (when user provides search terms)

```bash
node scripts/map-index.js --query "<terms>"
```

The query engine scores files by:
- Path match: +3 per term
- Export match: +5 per term
- Symbol match: +2 per term
- Role match: +1 per term

Results are sorted by score and capped at 20 files (configurable with `--max-files`).
Output is budget-capped at 8000 characters to stay injection-safe.

### Step 3: STATS (structural overview)

```bash
node scripts/map-index.js --stats
```

Outputs: file count, line count, export count, dependency edge count, route count,
package script count, verification command count, breakdown by language, and
breakdown by role.

### Step 4: SLICE (agent context injection)

When another skill or orchestrator needs a map slice for agent injection:

1. Run `node scripts/map-index.js --slice "<scope terms>" --max-files 15`
2. Inject the generated compact block:

```
=== MAP SLICE: <terms> ===
Generated: <timestamp>
Verification: npm run test | npm run typecheck
<score> <role>  <path>  [<top exports>]  (<lines>L)
...
=== END MAP SLICE ===
```

3. The calling skill injects this block into the agent's prompt alongside
   CLAUDE.md and rules-summary.md

**Token budget:** A 15-file slice is typically 800-1200 tokens. This replaces
2000-5000 tokens of exploratory Glob/Grep results that agents would otherwise
spend finding relevant files.

### Step 5: STALENESS CHECK

Before injecting an existing map into a long-running campaign, run:

```bash
node scripts/map-index.js --stale
```

The command exits `0` when the map is current and `2` when indexed source files
were added, changed, or removed. Refresh with:

```bash
node scripts/map-index.js --generate --force --root .
```

## Fleet Integration

Fleet agents receive map slices automatically when `/map` index exists:

1. Before spawning each wave, Fleet checks if `.planning/map/index.json` exists
2. If it exists: Fleet runs a slice scoped to each agent's assigned domain
3. The generated slice is prepended to the agent's context alongside CLAUDE.md
   and rules-summary.md
4. If the index does not exist: Fleet proceeds without a map slice (no error)

**Context injection order:**
1. CLAUDE.md content
2. `.claude/agent-context/rules-summary.md`
3. **Map slice** (scoped to agent's domain/direction)
4. Campaign-specific direction and scope
5. Discovery briefs from previous waves

## Contextual Gates

**Disclosure:** "Generating codebase map. Creates `.planning/map/index.json`."
**Reversibility:** green — creates `.planning/map/index.json` only; undo by deleting `.planning/map/`.
**Trust gates:**
- Any: generate index, query, stats, slice.

## Quality Gates

- Index must generate without errors on any supported project
- Query must return results sorted by relevance score
- Stats output must be human-scannable in under 5 seconds
- Slice output must stay under 2000 tokens for a 15-file result
- Index must handle 100K+ line repos without hanging (iterative walker, no recursion limits)
- Cache must prevent redundant regeneration within the TTL window
- Stale checks must detect added, changed, and removed indexed source files
- Slice output must include relevant verification commands when package scripts exist

## Fringe Cases

- **No source files found**: Generator writes an empty index (`fileCount: 0`). Query returns no results. Not an error.
- **`.planning/` does not exist**: Generator creates `.planning/map/` automatically via `mkdirSync({ recursive: true })`.
- **Index file missing when querying**: Error message: "Index not found. Run `node scripts/map-index.js --generate` first."
- **Binary or unsupported files**: Silently skipped. Only files with recognized language extensions are indexed.
- **Very large repos (10K+ files)**: The walker is iterative (stack-based), not recursive. No stack overflow risk. May take 5-10 seconds on first run.
- **Windows paths**: All stored paths use forward slashes for cross-platform consistency.

## Exit Protocol

After generation:
```
Index written: <path>
  <file count> files, <edge count> dependency links
  <route count> routes, <verification command count> verification commands
```

After query:
```
Results for "<terms>" (<count> matches):
  Score  Role        Path
  -----------------------------------------------
  <results>
```

After stats: print the full statistics block.

After slice: output the formatted slice block ready for injection.

After stale check:
```
Map index is current.
```

or:

```
Map index is stale.
Changed: <paths>
Added: <paths>
Removed: <paths>
```

Reversibility: green — delete `.planning/map/` to remove all generated artifacts; no source files modified.

© SethGammon · MIT · SethGammon/Citadel

Similar skills

All skills for Agent setup: memory, context, orchestration →

map by other authors comes first.

map Yeachan-Heo This Claude Code skill routes a task to the matching skill in the collection. It maps work to a delivery stage or a specific workflow, but does not carry out the task itself. CX Codex +1 160installs modernize-map official Anthropic modernize-map builds an interactive dependency and topology map of a legacy codebase, showing entry points and data flows. Helps map connections between modules before refactoring. CX Codex +1 ★ 47,914repo stars codependix-navigate organizzolini codependix-navigate teaches the agent to answer dependency questions: how project A reaches C, what breaks if a file changes. Uses codependix path or graphs already committed to the repo. CX Codex +1 364installs qe-code-intelligence proffesor-for-testing qe-code-intelligence builds a semantic code index, dependency graphs and knowledge graphs. Helps understand unfamiliar codebases, trace call chains, and find code by meaning rather than keywords. CX Codex +1 122installs codependix-export organizzolini codependix-export — a skill for Claude Code that runs codependix dependency graph exports and boundary checks. Handles report verification, boundary violations, and artifact generation. CX Codex +1 364installs mcp-codebase-index MikeRecognex mcp-codebase-index parses a codebase into functions, classes and dependencies, then hands the agent 18 query tools instead of full file reads. CX Codex +1 ★ 63repo stars Codeix montanetech Codeix — an MCP server for Claude Code and seven other platforms. It builds a structured index of symbols, references, and callers across the codebase so the agent stops grepping and starts working. CX Codex +1 ★ 9repo stars

From the same set55

The whole set →
prd prd turns an app idea into a structured product requirements document, asking about decisions that affect its shape. Use it before handing a project plan to Archon. CX Codex +1 ★ 937repo stars organize organize — a skill that audits and corrects project structure: checks file placement, moves files to match conventions, updates imports. Leaves code inside files untouched. CX Codex +1 ★ 937repo stars create-app create-app — a skill for Claude Code and Codex that builds applications from a single prompt. It routes work across five distinct tiers, passing through PRD, architecture, and verified execution phases. CX Codex +1 ★ 937repo stars postmortem The postmortem skill reviews completed campaigns or incidents using project files, telemetry, and Git history. It shows what failed and which safeguards caught it. CX Codex +1 ★ 937repo stars phase-validator The phase-validator subagent for Claude Code compares phase handoff reports with exit conditions and returns a pass or fail verdict. It checks automated development pipelines. CX Codex ★ 937repo stars fleet fleet splits a big job into campaigns and runs them in waves of 2–3 agents, handing each wave's findings to the next. Fits when the tasks don't touch the same files. CX Codex ★ 937repo stars workspace workspace coordinates changes across multiple repositories in a single task. Breaks work into waves, runs campaigns per repo, verifies contracts between them. CX Codex +1 ★ 937repo stars create-skill create-skill interviews you about a recurring workflow, compiles it into a structured SKILL.md file, and tests it against real project files. CX Codex +1 ★ 937repo stars

Project sponsors

Companies that keep this analytics open