Guide for setup Codemap CLI for intelligent codebase visualization and navigation
User Input:
$ARGUMENTS
Ask the user where they want to store the configuration:
Options:
Project level (shared via git) - Configuration tracked in version control, shared with team
./CLAUDE.md./.claude/settings.jsonProject level (personal preferences) - Configuration stays local, not tracked in git
./CLAUDE.local.md./.claude/settings.local.json.gitignore, add them if notUser level (global) - Configuration applies to all projects for this user
~/.claude/CLAUDE.md~/.claude/settings.jsonStore the user's choice and use the appropriate paths in subsequent steps.
Check whether codemap is installed by running codemap -help.
If not installed, proceed with setup.
Read the following documentation to understand Codemap's capabilities:
brew tap JordanCoin/tap && brew install codemap
scoop bucket add codemap https://github.com/JordanCoin/scoop-codemap
scoop install codemap
After installation, verify codemap works:
codemap .
Use the path determined in step 1. Once Codemap is successfully installed, update the appropriate CLAUDE.md file with the following content:
## Use Codemap CLI for Codebase Navigation
Codemap CLI is available for intelligent codebase visualization and navigation.
**Required Usage** - You MUST use `codemap --diff --ref master` to research changes different from default branch, and `git diff` + `git status` to research current working state.
### Quick Start
```bash
codemap . # Project tree
codemap --only swift . # Just Swift files
codemap --exclude .xcassets,Fonts,.png . # Hide assets
codemap --depth 2 . # Limit depth
codemap --diff # What changed vs main
codemap --deps . # Dependency flow
| Flag | Description |
|---|---|
--depth, -d <n> | Limit tree depth (0 = unlimited) |
--only <exts> | Only show files with these extensions |
--exclude <patterns> | Exclude files matching patterns |
--diff | Show files changed vs main branch |
--ref <branch> | Branch to compare against (with --diff) |
--deps | Dependency flow mode |
--importers <file> | Check who imports a file |
--skyline | City skyline visualization |
--json | Output JSON |
Smart pattern matching - no quotes needed:
.png - any .png fileFonts - any /Fonts/ directory*Test* - glob patternSee what you're working on:
codemap --diff
codemap --diff --ref develop
if the default branch is not `main`, but instead `master` (or something else) update content accordingly:
- use `codemap --diff --ref master` instead of regular `codemap --diff`
## 7. Update .gitignore file
Update .gitignore file to include `.codemap/` directory:
```text
.codemap/
Run a quick test to verify everything works:
codemap .
codemap --diff
Use the settings path determined in step 1. Create the settings file if it doesn't exist and add the following content:
{
"hooks": {
"session-start": "codemap hook session-start && echo 'git diff:' && git diff --stat && echo 'git status:' && git status"
}
}
if default branch is not main, but instead master (or something else) update content accordingly:
codemap hook session-start --ref=master instead of regular codemap hook session-start--ref=master flag.Ask user whether he want to add any other hooks and provide list of options with descriptions. Add hooks that he asks for.
| Command | Trigger | Description |
|---|---|---|
codemap hook session-start | SessionStart | Full tree, hubs, branch diff, last session context |
codemap hook pre-edit | PreToolUse (Edit|Write) | Who imports file + what hubs it imports |
codemap hook post-edit | PostToolUse (Edit|Write) | Impact of changes (same as pre-edit) |
codemap hook prompt-submit | UserPromptSubmit | Hub context for mentioned files + session progress |
codemap hook pre-compact | PreCompact | Saves hub state to .codemap/hubs.txt |
codemap hook session-stop | SessionEnd | Edit timeline with line counts and stats |
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "codemap hook session-start"
}
]
}
],
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "codemap hook pre-edit"
}
]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "codemap hook post-edit"
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "codemap hook prompt-submit"
}
]
}
],
"PreCompact": [
{
"hooks": [
{
"type": "command",
"command": "codemap hook pre-compact"
}
]
}
],
"SessionEnd": [
{
"hooks": [
{
"type": "command",
"command": "codemap hook session-stop"
}
]
}
]
}
}