Back to Details

codemap

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codemap

Codemap

Codemap gives you instant architectural context about any codebase. Use it proactively before exploring or modifying code.
Codemap 可为你提供任意代码库的即时架构上下文信息。建议你在浏览或修改代码前主动使用它。

Commands

命令

bash
codemap .                     # Project structure and top files
codemap --deps                # Dependency flow (imports/functions)
codemap --diff                # Changes vs main branch
codemap --diff --ref <branch> # Changes vs specific branch
codemap handoff .             # Build + save handoff artifact
codemap handoff --latest .    # Read latest saved handoff
codemap handoff --json .      # Machine-readable handoff payload
codemap handoff --since 2h .  # Limit timeline lookback when building
codemap handoff --prefix .    # Stable prefix snapshot only
codemap handoff --delta .     # Recent delta snapshot only
codemap handoff --detail a.go . # Lazy-load full detail for one changed file
bash
codemap .                     # 项目结构与核心文件
codemap --deps                # 依赖流向（导入/函数）
codemap --diff                # 与main分支的差异对比
codemap --diff --ref <branch> # 与指定分支的差异对比
codemap handoff .             # 生成并保存交接工件
codemap handoff --latest .    # 读取最近保存的交接信息
codemap handoff --json .      # 机器可读格式的交接数据
codemap handoff --since 2h .  # 生成时限制时间回溯范围（最近2小时）
codemap handoff --prefix .    # 仅生成稳定前缀快照
codemap handoff --delta .     # 仅生成近期增量快照
codemap handoff --detail a.go . # 懒加载某一变更文件的完整详情

When to Use

使用场景

ALWAYS run 
codemap .
when:

以下场景请务必运行 
codemap .
：

  • Starting any new task or feature
  • User asks "where is X?" or "what files handle Y?"
  • User asks about project structure or organization
  • You need to understand the codebase before making changes
  • Exploring unfamiliar code
  • 开始任何新任务或新功能开发时
  • 用户询问“X在哪里？”或“哪些文件处理Y？”时
  • 用户询问项目结构或组织方式时
  • 你需要在修改代码前先理解代码库时
  • 浏览不熟悉的代码时

ALWAYS run 
codemap --deps
when:

以下场景请务必运行 
codemap --deps
：

  • User asks "how does X work?" or "what uses Y?"
  • Refactoring or moving code
  • Need to trace imports or dependencies
  • Evaluating impact of changes
  • Finding hub files (most-imported)
  • 用户询问“X如何工作？”或“哪些模块使用Y？”时
  • 重构或迁移代码时
  • 需要追踪导入关系或依赖链时
  • 评估变更影响范围时
  • 查找核心枢纽文件（被导入次数最多的文件）时

ALWAYS run 
codemap --diff
when:

以下场景请务必运行 
codemap --diff
：

  • User asks "what changed?" or "what did I modify?"
  • Reviewing changes before commit
  • Summarizing work done on a branch
  • Assessing what might break
  • Use 
    --ref <branch>
    when comparing against something other than main
  • 用户询问“有哪些变更？”或“我修改了什么？”时
  • 提交前审查变更内容时
  • 总结分支上已完成的工作时
  • 评估可能出现的问题时
  • 若需与main以外的分支对比，使用 
    --ref <branch>
    参数

ALWAYS run 
codemap handoff
when:

以下场景请务必运行 
codemap handoff
：

  • Handing work from one agent to another (Claude, Codex, MCP client)
  • Resuming work after a break and you want a compact recap
  • User asks "what should the next agent know?"
  • You want a durable summary in 
    .codemap/handoff.latest.json
  • 在不同Agent之间交接工作时（如Claude、Codex、MCP客户端）
  • 中断后恢复工作，需要简洁的工作回顾时
  • 用户询问“下一个Agent需要了解哪些信息？”时
  • 你需要在 
    .codemap/handoff.latest.json
    中保存持久化的工作摘要时

Output Interpretation

输出解读

Tree View (
codemap .
)

树状视图（
codemap .
）

  • Shows file structure with language detection
  • Stars (★) indicate top 5 largest source files
  • Directories are flattened when empty (e.g., 
    src/main/java
    )
  • 显示文件结构并自动检测语言类型
  • 星号（★）标记前5个最大的源文件
  • 空目录会被扁平化展示（例如 
    src/main/java
    ）

Dependency Flow (
codemap --deps
)

依赖流向（
codemap --deps
）

  • External dependencies grouped by language
  • Internal import chains showing how files connect
  • HUBS section shows most-imported files
  • Function counts per file
  • 外部依赖按语言分组展示
  • 内部导入链展示文件间的关联关系
  • HUBS 部分展示被导入次数最多的文件
  • 显示每个文件的函数数量

Diff Mode (
codemap --diff
)

差异模式（
codemap --diff
）

  • (new)
    = untracked file
  • ✎
    = modified file
  • (+N -M)
    = lines added/removed
  • Warning icons show files imported by others (impact analysis)
  • (new)
    = 未被追踪的新文件
  • ✎
    = 已修改的文件
  • (+N -M)
    = 新增/删除的代码行数
  • 警告图标表示被其他文件导入的文件（影响范围分析）

Handoff (
codemap handoff
)

交接信息（
codemap handoff
）

  • layered output: 
    prefix
    (stable hubs/context) + 
    delta
    (recent changed-file stubs + timeline)
  • changed file transport uses stubs (
    path
    , 
    hash
    , 
    status
    , 
    size
    ) for lower context cost
  • risk_files
    highlights high-impact changed files when dependency context is available
  • includes deterministic hashes (
    prefix_hash
    , 
    delta_hash
    , 
    combined_hash
    ) and cache metrics
  • --latest
    reads saved artifact without rebuilding
  • 分层输出：
    prefix
    （稳定的枢纽文件/上下文） + 
    delta
    （近期变更文件的存根信息 + 时间线）
  • 变更文件传输使用存根信息（
    path
    、
    hash
    、
    status
    、
    size
    ）以降低上下文成本
  • 当依赖上下文可用时，
    risk_files
    会高亮显示高影响的变更文件
  • 包含确定性哈希值（
    prefix_hash
    、
    delta_hash
    、
    combined_hash
    ）和缓存指标
  • --latest
    参数可直接读取已保存的工件，无需重新生成

Daemon and Hooks

守护进程与钩子

  • With daemon state: handoff includes richer timeline and better risk context.
  • Without daemon state: handoff still works using git-based changed files.
  • Hook behavior: 
    • session-stop
      writes 
      .codemap/handoff.latest.json
    • session-start
      may show recent handoff summary (24h freshness window)
    • session-start structure output is capped/adaptive for large repos
  • 开启守护进程状态时：交接信息包含更丰富的时间线和更精准的风险上下文
  • 未开启守护进程状态时：交接信息仍可基于Git追踪的变更文件生成
  • 钩子行为： 
    • session-stop
      会写入 
      .codemap/handoff.latest.json
      文件
    • session-start
      可能会显示最近24小时内的交接摘要
    • 对于大型代码库，session-start输出的结构会自适应限制内容规模

Examples

示例

User asks: "Where is the authentication handled?" Action: Run 
codemap .
then 
codemap --deps
to find auth-related files and trace their connections.
User asks: "What have I changed on this branch?" Action: Run 
codemap --diff
to see all modifications with impact analysis.
User asks: "How does the API connect to the database?" Action: Run 
codemap --deps
to trace the import chain from API to database files.
User asks: "I want to refactor the utils module" Action: Run 
codemap --deps
first to see what depends on utils before making changes.
User asks: "I'm switching to another agent, what should I pass along?" Action: Run 
codemap handoff .
and share the summary (or 
--json
for tools).
User asks: "I just came back, what was in progress?" Action: Run 
codemap handoff --latest .
and continue from that state.
用户提问： “认证功能在哪里实现？” 操作： 先运行 
codemap .
，再运行 
codemap --deps
，查找与认证相关的文件并追踪它们的关联关系。
用户提问： “我在这个分支上做了哪些修改？” 操作： 运行 
codemap --diff
查看所有修改内容及影响范围分析。
用户提问： “API是如何与数据库建立连接的？” 操作： 运行 
codemap --deps
追踪从API到数据库文件的导入链。
用户提问： “我想重构utils模块” 操作： 先运行 
codemap --deps
，查看哪些模块依赖utils，再进行修改。
用户提问： “我要切换到另一个Agent，需要传递哪些信息？” 操作： 运行 
codemap handoff .
并分享生成的摘要（或使用 
--json
参数生成工具可读格式）。
用户提问： “我刚回来，之前在做什么？” 操作： 运行 
codemap handoff --latest .
，基于该状态继续工作。