setup-codemap-cli

用户输入：

$ARGUMENTS

Codemap CLI 设置指南

1. 确定设置范围

询问用户想将配置存储在哪里：

选项：

1. 项目级（通过 git 共享） - 配置纳入版本控制并与团队共享

   • CLAUDE.md 更新至：./CLAUDE.md
   • Hook 设置写入：./.claude/settings.json

2. 项目级（个人偏好） - 配置保留在本地，不纳入 git 跟踪

   • CLAUDE.md 更新至：./CLAUDE.local.md
   • Hook 设置写入：./.claude/settings.local.json
   • 确认这些文件已列在 .gitignore 中；如果没有，将其添加进去

3. 用户级（全局） - 配置适用于此用户的所有项目

   • CLAUDE.md 更新至：~/.claude/CLAUDE.md
   • Hook 设置写入：~/.claude/settings.json

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

2. 检查 Codemap 是否已安装

运行 codemap -help，检查是否已安装 codemap。

如果尚未安装，请继续设置。

3. 加载 Codemap 文档

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

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

4. 引导用户完成安装

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. 验证安装

安装后，验证 codemap 是否正常工作：

codemap .

6. 更新 CLAUDE.md 文件

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

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

选项

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

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

• .png - 任意 .png 文件
• Fonts - 任意 /Fonts/ 目录
• *Test* - glob 模式

差异模式

查看当前正在处理的内容：

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/

8. 测试 Codemap

运行快速测试，验证一切是否正常：

codemap .
codemap --diff

9. 将 Hook 添加到设置文件

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

  {
      "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 标志。

• 询问用户是否要添加其他 Hook，并提供带说明的选项列表。添加用户要求的 Hook。

可用 Hook

命令	触发条件	描述
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	包含行数和统计信息的编辑时间线

完整 Hook 配置文件示例

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