setup-codemap-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

User Input:

text

$ARGUMENTS

用户输入:

text

$ARGUMENTS

Guide for setup Codemap CLI

Codemap CLI 安装指南

1. Determine setup context

1. 确定安装上下文

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 updates go to:
```
./CLAUDE.md
```
- Hook settings go to:
```
./.claude/settings.json
```
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
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.

询问用户希望将配置存储在何处：

选项：

项目级别（通过 git 共享） - 配置纳入版本控制，与团队共享
- CLAUDE.md 更新路径：
```
./CLAUDE.md
```
- Hook 设置路径：
```
./.claude/settings.json
```
项目级别（个人偏好） - 配置仅保存在本地，不纳入 git 版本控制
- CLAUDE.md 更新路径：
```
./CLAUDE.local.md
```
- Hook 设置路径：
```
./.claude/settings.local.json
```
- 确认这些文件已列入
```
.gitignore
```
  ，若未列入则添加
用户级别（全局） - 配置适用于该用户的所有项目
- CLAUDE.md 更新路径：
```
~/.claude/CLAUDE.md
```
- Hook 设置路径：
```
~/.claude/settings.json
```

保存用户的选择，并在后续步骤中使用相应的路径。

2. Check if Codemap is already installed

2. 检查 Codemap 是否已安装

Check whether codemap is installed by running

codemap -help

If not installed, proceed with setup.

通过运行

codemap -help

检查 Codemap 是否已安装。

若未安装，则继续进行安装。

3. Load Codemap documentation

3. 加载 Codemap 文档

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

阅读以下文档以了解 Codemap 的功能：

加载 https://raw.githubusercontent.com/JordanCoin/codemap/refs/heads/main/README.md 以了解 Codemap 是什么及其功能

4. Guide user through installation

4. 引导用户完成安装

macOS/Linux (Homebrew)

bash

brew tap JordanCoin/tap && brew install codemap

bash

brew tap JordanCoin/tap && brew install codemap

Windows (Scoop)

bash

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

bash

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

5. Verify installation

5. 验证安装

After installation, verify codemap works:

bash

codemap .

安装完成后，验证 Codemap 是否可用：

bash

codemap .

6. Update CLAUDE.md file

6. 更新 CLAUDE.md 文件

Use the path determined in step 1. Once Codemap is successfully installed, update the appropriate CLAUDE.md file with the following content:

markdown

undefined

使用步骤 1 中确定的路径。Codemap 安装成功后，将以下内容更新到对应的 CLAUDE.md 文件中：

markdown

undefined

Use Codemap CLI for Codebase Navigation

使用 Codemap CLI 进行代码库导航

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.

Codemap CLI 可用于智能代码库可视化与导航。

必填用法 - 你必须使用

codemap --diff --ref master

来研究与默认分支不同的更改，并使用

git diff

git status

来研究当前工作状态。

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

bash

codemap .                    # 项目树
codemap --only swift .       # 仅显示 Swift 文件
codemap --exclude .xcassets,Fonts,.png .  # 隐藏资源文件
codemap --depth 2 .          # 限制树的深度
codemap --diff               # 显示与主分支相比的更改
codemap --deps .             # 依赖关系流

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

标志	描述
`--depth, -d <n>`	限制树的深度（0 = 无限制）
`--only <exts>`	仅显示带有指定扩展名的文件
`--exclude <patterns>`	排除匹配指定模式的文件
`--diff`	显示与主分支相比已更改的文件
`--ref <branch>`	对比的分支（配合 --diff 使用）
`--deps`	依赖关系流模式
`--importers <file>`	查看哪些文件导入了指定文件
`--skyline`	城市天际线可视化模式
`--json`	输出 JSON 格式

智能模式匹配 - 无需引号：

```
.png
```
- 所有
```
.png
```
文件
```
Fonts
```
- 所有
```
/Fonts/
```
目录
```
*Test*
```
- glob 模式

Diff Mode

差异模式

See what you're working on:

bash

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`

查看当前工作内容：

bash

codemap --diff
codemap --diff --ref develop

如果默认分支不是

main

，而是

master

（或其他分支），请相应更新内容：

使用

codemap --diff --ref master

替代常规的

codemap --diff

7. Update .gitignore file

7. 更新 .gitignore 文件

Update .gitignore file to include

.codemap/

directory:

text

.codemap/

更新

.gitignore

文件，添加

.codemap/

text

.codemap/

8. Test Codemap

8. 测试 Codemap

Run a quick test to verify everything works:

bash

codemap .
codemap --diff

运行快速测试以验证所有功能正常：

bash

codemap .
codemap --diff

9. Add hooks to settings file

9. 向设置文件添加 Hooks

Use the settings path determined in step 1. Create the settings file if it doesn't exist and add the following content:

json

{
    "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.

使用步骤 1 中确定的设置路径。如果设置文件不存在则创建，并添加以下内容：

json

{
    "hooks": {
        "session-start": "codemap hook session-start && echo 'git diff:' && git diff --stat && echo 'git status:' && git status"
    }
}

如果默认分支不是

main

，而是

master

（或其他分支），请相应更新内容：

使用

codemap hook session-start --ref=master

替代常规的

codemap hook session-start

其余命令也需添加
```
--ref=master
```
标志。

询问用户是否需要添加其他 Hooks，并提供带有描述的选项列表。添加用户要求的 Hooks。

Available Hooks

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

命令	触发时机	描述
`codemap hook session-start`	SessionStart	完整树状结构、核心模块、分支差异、上一次会话上下文
`codemap hook pre-edit`	PreToolUse (Edit\|Write)	查看哪些文件导入了当前文件 + 当前文件导入的核心模块
`codemap hook post-edit`	PostToolUse (Edit\|Write)	更改的影响（与 pre-edit 内容相同）
`codemap hook prompt-submit`	UserPromptSubmit	提及文件的核心模块上下文 + 会话进度
`codemap hook pre-compact`	PreCompact	将核心模块状态保存到 .codemap/hubs.txt
`codemap hook session-stop`	SessionEnd	包含行数统计的编辑时间线

Example of file with full hooks configuration

完整 Hooks 配置文件示例

json

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

json

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