setup-codemap-cli

User Input:

$ARGUMENTS

Guide for setup Codemap CLI

1. Determine setup context

Ask the user where they want to store the configuration:

Options:

1. Project level (shared via git) - Configuration tracked in version control, shared with team

• CLAUDE.md updates go to: ./CLAUDE.md
• Hook settings go to: ./.claude/settings.json

1. Project level (personal preferences) - Configuration stays local, not tracked in git

• CLAUDE.md updates go to: ./CLAUDE.local.md
• Hook settings go to: ./.claude/settings.local.json
• Verify these files are listed in .gitignore, add them if not

1. User level (global) - Configuration applies to all projects for this user

• CLAUDE.md updates go to: ~/.claude/CLAUDE.md
• Hook settings go to: ~/.claude/settings.json

Store the user's choice and use the appropriate paths in subsequent steps.

2. Check if Codemap is already installed

Check whether codemap is installed by running codemap -help.

If not installed, proceed with setup.

3. Load Codemap documentation

Read the following documentation to understand Codemap's capabilities:

• Load <https://raw.githubusercontent.com/JordanCoin/codemap/refs/heads/main/README.md> to understand what Codemap is and its capabilities

4. Guide user through installation

macOS/Linux (Homebrew)

brew tap JordanCoin/tap && brew install codemap

Windows (Scoop)

scoop bucket add codemap https://github.com/JordanCoin/scoop-codemap
scoop install codemap

5. Verify installation

After installation, verify codemap works:

codemap .

6. Update CLAUDE.md file

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

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

### Options

| 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` file
- `Fonts` - any `/Fonts/` directory
- `*Test*` - glob pattern

### Diff Mode

See 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:

.codemap/

8. Test Codemap

Run a quick test to verify everything works:

codemap .
codemap --diff

9. Add hooks to settings file

• 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:

• use codemap hook session-start --ref=master instead of regular codemap hook session-start
• For rest of commands also add --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.

Available Hooks

| 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 |

Example of file with full hooks configuration

{
  "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"
          }
        ]
      }
    ]
  }
}