name: codemap-creator
allowed-tools: Task, Bash
argument-hint: " [--ignore ] | --update [--diff | --pr ]"
description: Generate or update hierarchical code map from any directory as root, with nested tree structure (project)
context: fork
model: opus

Code Map Creator

Generate or update a hierarchical code map using Claude Code's built-in LSP tools. Maps functions, classes, variables, and imports in a nested tree structure.

Modes

Create Mode (default)

Generate a new codemap from scratch:

/codemap-creator src/
/codemap-creator . --ignore "node_modules,dist"

Update Mode

Update an existing codemap with only changed files:

/codemap-creator --update .claude/maps/code-map-src-a3f9e.json --diff
/codemap-creator --update .claude/maps/code-map-src-a3f9e.json --pr 456

Arguments

Create Mode

• Root directory (required): Starting point for the tree
• /codemap-creator src/ → maps from src/ as root
• /codemap-creator backend/services → maps from services/ as root

• /codemap-creator . → maps entire project as root

• Ignore patterns (optional): Skip files/directories

• /codemap-creator src/ --ignore "*.test.ts,node_modules"

Update Mode

• --update (required): Path to existing codemap to update
• --diff (optional): Use git diff to find changed files (uncommitted + staged)
• --pr (optional): Use GitHub PR to find changed files (via gh)

If no diff source specified with --update, defaults to --diff.

Hierarchical Output

The codemap shows a nested tree structure from your chosen root:

root_dir/
├── subdir1/
│   ├── file1.ts
│   │   └── symbols: [class UserService, function getUser...]
│   └── nested/
│       └── file2.ts
│           └── symbols: [interface Config...]
├── subdir2/
│   └── file3.ts
│       └── symbols: [function helper...]
└── index.ts
    └── symbols: [export *, function main...]

Instructions

Step 1: Parse Input and Detect Mode

The user invoked this skill with arguments: $ARGUMENTS

Determine mode from these arguments:

Update Mode (if --update present):
1. Extract codemap path after --update
2. Detect diff source:
- --diff → use git diff --name-only + git diff --staged --name-only
- --pr <id> → use gh pr diff <id> --name-only
- Default to --diff if no source specified
3. Get list of changed files

Create Mode (default):
1. Root directory (required, first argument)
- If not provided, default to . (current directory)
- Validate directory exists
2. Ignore patterns (optional --ignore)
- Comma-separated patterns to skip

Step 2: Get Changed Files (Update Mode Only)

Run the appropriate command to get changed files:

# For --diff (default)
git diff --name-only && git diff --staged --name-only

# For --pr <id>
gh pr diff <id> --name-only

Filter to only files within the codemap's root directory.

Step 3: Launch Agent

Create Mode:

subagent_type: "essentials:codemap-creator-default"
run_in_background: true
prompt: "MODE: create\nRoot: <root_dir>\nIgnore: <patterns or none>"

Update Mode:

subagent_type: "essentials:codemap-creator-default"
run_in_background: true
prompt: "MODE: update\nCodemap: <codemap_path>\nChanged files:\n- file1.ts\n- file2.ts\n..."

Output a status message like "Creating code map..." and end your turn. The system wakes you when the agent finishes.

Step 4: Report Result

Create Mode:

## Hierarchical Code Map Created (LSP)

**Root**: <root_dir>
**Map**: .claude/maps/code-map-{name}-{hash5}.json

### Totals

| Metric | Count |
|--------|-------|
| Directories | X |
| Files | X |
| Symbols | X |
| Exported | X |

Next: Read the map file for hierarchical code navigation.

Update Mode:

## Code Map Updated (LSP)

**Map**: <codemap_path>
**Source**: git diff | PR #X
**Files Updated**: X
**Files Added**: X
**Files Removed**: X

### Changes

| File | Action | Symbols |
|------|--------|---------|
| path/to/file.ts | updated | 5 |
| path/to/new.ts | added | 3 |
| path/to/old.ts | removed | - |

Next: Codemap is current with latest changes.

Error Handling

Example Usage

# Create mode
/codemap-creator src/
/codemap-creator backend/services
/codemap-creator frontend/components --ignore "*.test.tsx,*.stories.tsx"
/codemap-creator .

# Update mode - git diff (uncommitted changes)
/codemap-creator --update .claude/maps/code-map-src-a3f9e.json
/codemap-creator --update .claude/maps/code-map-src-a3f9e.json --diff

# Update mode - from PR
/codemap-creator --update .claude/maps/code-map-src-a3f9e.json --pr 456