with one click
codemap
// Generate comprehensive hierarchical codemaps for UNFAMILIAR repositories. Expensive operation - only use when explicitly asked for codebase documentation or initial repository mapping
// Generate comprehensive hierarchical codemaps for UNFAMILIAR repositories. Expensive operation - only use when explicitly asked for codebase documentation or initial repository mapping
Clone important project dependency source code into an ignored local workspace so OpenCode can inspect library internals. Use when the user asks to clone dependencies, inspect dependency/source internals, understand SDK/framework behavior from source, debug library implementation details, or make core dependency repos locally readable. Do not use for ordinary API/docs questions where @librarian is enough.
Simplifies code for clarity without changing behavior. Use for readability, maintainability, and complexity reduction after behavior is understood.
| name | codemap |
| description | Generate comprehensive hierarchical codemaps for UNFAMILIAR repositories. Expensive operation - only use when explicitly asked for codebase documentation or initial repository mapping |
You help users understand and map repositories by creating hierarchical codemaps.
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).
src/**/*.ts, package.json, etc.**/*.test.ts, **/*.spec.ts, tests/**, __tests__/**docs/**, *.md (except root README.md if needed), LICENSEnode_modules/**, dist/**, build/**, *.min.js.gitignore automaticallynode ~/.config/opencode/skills/codemap/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 detectioncodemap.md files in all relevant subdirectoriescodemap.md file.node ~/.config/opencode/skills/codemap/scripts/codemap.mjs changes \
--root ./
Review the output - It shows:
Only update affected codemaps - Spawn one fixer per affected folder to update its codemap.md.
Run update to save new state:
node ~/.config/opencode/skills/codemap/scripts/codemap.mjs update \
--root ./
Once all specific directories are mapped, the Orchestrator must create or update the root codemap.md. This file serves as the Master Entry Point for any agent or human entering the repository.
package.json, index.ts, plugin.json) and the project's overall purpose.codemap.md, extract its Responsibility summary and include it in a table or list in the root map.OpenCode auto-loads AGENTS.md into agent context on every session. To ensure agents automatically discover and use the codemap, update (or create) AGENTS.md at the repo root:
AGENTS.md already exists and already contains a ## Repository Map section, skip this step โ the reference is already set up.AGENTS.md exists but has no ## Repository Map section, append the section below.AGENTS.md doesn't exist, create it with the section below.## Repository Map
A full codemap is available at `codemap.md` in the project root.
Before working on any task, read `codemap.md` to understand:
- Project architecture and entry points
- Directory responsibilities and design patterns
- Data flow and integration points between modules
For deep work on a specific folder, also read that folder's `codemap.md`.
This is idempotent โ repeated codemap runs will detect the existing section and skip. No duplication.
Fixers are responsible for writing codemap.md files during this workflow. Use precise technical terminology to document the implementation:
Example codemap:
# src/agents/
## Responsibility
Defines agent personalities and manages their configuration lifecycle.
## Design
Each agent is a prompt + permission set. Config system uses:
- Default prompts (orchestrator.ts, explorer.ts, etc.)
- User overrides from ~/.config/opencode/oh-my-opencode-slim.json
- Permission wildcards for skill/MCP access control
## Flow
1. Plugin loads โ calls getAgentConfigs()
2. Reads user config preset
3. Merges defaults with overrides
4. Applies permission rules (wildcard expansion)
5. Returns agent configs to OpenCode
## Integration
- Consumed by: Main plugin (src/index.ts)
- Depends on: Config loader, skills registry
Example Root Codemap (Atlas):
# Repository Atlas: oh-my-opencode-slim
## Project Responsibility
A high-performance, low-latency agent orchestration plugin for OpenCode, focusing on specialized sub-agent delegation and multiplexer-assisted child sessions.
## System Entry Points
- `src/index.ts`: Plugin initialization and OpenCode integration.
- `package.json`: Dependency manifest and build scripts.
- `oh-my-opencode-slim.json`: User configuration schema.
## Directory Map (Aggregated)
| Directory | Responsibility Summary | Detailed Map |
|-----------|------------------------|--------------|
| `src/agents/` | Defines agent personalities (Orchestrator, Explorer) and manages model routing. | [View Map](src/agents/codemap.md) |
| `src/features/` | Core logic for tmux integration and session state. | [View Map](src/features/codemap.md) |
| `src/config/` | Implements the configuration loading pipeline and environment variable injection. | [View Map](src/config/codemap.md) |