# Codemap

Generate comprehensive hierarchical codemaps for UNFAMILIAR repositories.

- Repository: https://github.com/alvinunreal/oh-my-opencode-slim (10062 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add alvinunreal/oh-my-opencode-slim --skill codemap -g -a claude-code -y`
Codex: `npx skills add alvinunreal/oh-my-opencode-slim --skill codemap -g -a codex -y`
Cursor: `npx skills add alvinunreal/oh-my-opencode-slim --skill codemap -g -a cursor -y`
Gemini CLI: `npx skills add alvinunreal/oh-my-opencode-slim --skill codemap -g -a gemini-cli -y`

## Description

Generate comprehensive hierarchical codemaps for UNFAMILIAR repositories. Expensive operation - only use when explicitly asked for codebase documentation or initial repository mapping

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Codemap Skill

You help users understand and map repositories by creating hierarchical codemaps.

## When to Use

- User asks to understand/map a repository
- User wants codebase documentation
- Starting work on an unfamiliar codebase

## Workflow

### Step 1: Check for Existing State

**First, check if `.slim/codemap.json` exists in the repo root.**

If it does not exist, check for legacy state at `.slim/cartography.json`.

If legacy state exists: move `.slim/cartography.json` to `.slim/codemap.json`, then continue with change detection.

If `.slim/codemap.json` exists: Skip to Step 3 (Detect Changes) - no need to re-initialize.

If neither file exists: Continue to Step 2 (Initialize).

### Step 2: Initialize (Only if no state exists)

1. **Analyze the repository structure** - List files, understand directories
2. **Infer patterns** for **core code/config files ONLY** to include:
   - **Include**: `src/**/*.ts`, `package.json`, etc.
   - **Exclude (MANDATORY)**: Do NOT include tests, documentation, or translations.
     - Tests: `**/*.test.ts`, `**/*.spec.ts`, `tests/**`, `__tests__/**`
     - Docs: `docs/**`, `*.md` (except root `README.md` if needed), `LICENSE`
     - Build/Deps: `node_modules/**`, `dist/**`, `build/**`, `*.min.js`
   - Respect `.gitignore` automatically
3. **Run codemap.mjs init** (`scripts/codemap.mjs` is relative to this skill's base directory, the host prints it as `Base directory for this skill`):

```bash
node scripts/codemap.mjs init \
  --root ./ \
  --include "src/**/*.ts" \
  --exclude "**/*.test.ts" --exclude "dist/**" --exclude "node_modules/**"
```

This creates:
- `.slim/codemap.json` - File and folder hashes for change detection
- Empty `codemap.md` files in all relevant subdirectories

4. **Delegate codemap writing to Fixer agents** - Spawn one fixer per folder to read code and create or update its specific `codemap.md` file.

### Step 3: Detect Changes (If state already exists)

The rest: https://github.com/alvinunreal/oh-my-opencode-slim/blob/HEAD/src/skills/codemap/SKILL.md