@whenlabs/when

六大工具。一次安装。

一个可安装的统一工具包，将六个 WhenLabs 开发者工具引入您的 Claude Code / AI 编码代理工作流。安装后，所有工具都将作为 MCP 工具在每个会话中可用——Claude 会在相关时自动使用它们。

其中五个工具（stale、envalid、berth、aware、vow）具有 CLI 扫描模式并按计划运行。Velocity 是第六个工具——它始终处于运行状态且是嵌入式的（基于 SQLite），因此它没有 CLI 扫描模式，也不会出现在 doctor/watch/init/ci 的输出中。

安装

npx @whenlabs/when install

这是一次性设置。安装后，所有六个工具在您使用 Claude Code 打开的每个项目中都可用。

功能说明

运行 npx @whenlabs/when install 将会：

在您的 Claude Code 配置中注册一个单一 MCP 服务器 (whenlabs) —— 所有六个工具（包括 velocity）都由同一个服务器提供服务
注入 CLAUDE.md 指令，以便 Claude 知道何时自动使用每个工具——并且优先使用它们而不是 shell 命令
清理任何旧的 velocity-mcp 注册（velocity 现在已捆绑在一起）

连接后，Claude 可以直接调用任何工具，无需您询问。例如，在重构后，Claude 可能会运行 stale_scan 来检查文档漂移，或者在发布前运行 vow_check 来验证许可证。

主动后台扫描

工具会按计划在后台自动运行，并在 Claude Code 状态栏中报告结果：

工具	间隔	状态栏显示
berth	15 分钟	`ports:N` — 发现端口冲突
stale	30 分钟	`stale:N` — 文档与代码不一致
envalid	30 分钟	`env:N` — .env 验证问题
vow	60 分钟	`lic:N?` — 发现未知许可证
aware	60 分钟	`aware:stale` — AI 上下文文件已过期

仅显示问题——如果一切正常，状态栏将保持整洁。当 Claude 在状态栏中看到问题时，它会主动告知您并提供修复方案。

MCP 工具

安装后，这些工具在每个会话中都可供 Claude 使用：

MCP 工具	功能说明
`velocity_start_task`	开始计时编码任务
`velocity_end_task`	结束计时并记录结果
`velocity_estimate`	估算计划任务的时间
`velocity_stats`	显示带有洞察的汇总性能统计信息
`velocity_history`	显示任务历史记录
`stale_scan`	检测文档漂移
`stale_fix`	自动修复文档漂移（错误的路径、死链接、虚构的环境变量）
`stale_auto_fix`	一次调用完成扫描 + 自动修复漂移
`envalid_validate`	根据模式验证 .env 文件
`envalid_detect`	在代码库中查找未记录的环境变量
`envalid_generate_schema`	通过代码分析生成 .env.schema
`envalid_auto_fix`	检测未记录的变量 + 自动生成模式条目
`berth_status`	显示活动端口和冲突
`berth_check`	扫描项目中的端口冲突
`berth_resolve`	自动解决端口冲突（终止或重新分配）
`berth_auto_resolve`	一次调用完成检查 + 自动解决冲突
`aware_init`	自动检测技术栈，生成 AI 上下文文件
`aware_doctor`	诊断项目健康状况和配置问题
`aware_auto_sync`	诊断 + 自动同步过期的 AI 上下文文件
`vow_scan`	扫描并汇总依赖项许可证
`vow_check`	根据策略验证许可证
`vow_hook_install`	安装提交前许可证检查钩子

此表显示了部分重点工具。运行 when <tool> --help 可查看每个工具的所有可用命令。

跨工具智能

当工具检测到与其他工具相关的问题时，会自动建议后续操作。例如，aware_init 在生成新文件时会触发 stale_scan，而 envalid_detect 在发现服务 URL 环境变量时会建议 berth_register。这些级联建议会作为“提示：”行出现在工具输出中。

多编辑器支持

将 MCP 服务器安装到除 Claude Code 之外的其他编辑器中：

npx @whenlabs/when install --cursor     # Cursor
npx @whenlabs/when install --vscode     # VS Code
npx @whenlabs/when install --windsurf   # Windsurf
npx @whenlabs/when install --all        # All supported editors

如果不加标志，install 仅针对 Claude Code。

CLI 使用

您也可以直接从命令行运行工具：

when init            # Onboard a project — bootstrap configs, run all tools, auto-fix
when config          # Show unified .whenlabs.yml config
when config init     # Generate .whenlabs.yml from existing tool configs
when config validate # Validate config structure
when stale scan
when stale fix       # Auto-fix documentation drift
when envalid validate
when envalid detect --generate  # Generate schema from code
when berth status
when berth resolve   # Auto-resolve port conflicts
when aware init
when vow scan
when vow hook install  # Install pre-commit license hook
when status          # Show installation status
when doctor          # Run all tools, show unified health report
when doctor --watch  # Continuous monitoring dashboard
when watch           # Background daemon for status line
when ci              # Run checks for CI (exits 1 on issues)

`when init`

一条命令即可完全引导任何项目：

引导 — 创建 .env.schema、.vow.json、.stale.yml，并根据您的项目注册 berth 端口
扫描 — 并行运行所有 5 个 CLI 工具
自动修复 — 如果检测到漂移，自动修复 stale 漂移
配置 — 从引导的配置中生成统一的 .whenlabs.yml

`when config`

管理统一的 .whenlabs.yml 项目配置。所有六个工具都从这个单一文件读取设置，而不是单独的配置文件。子命令：init（从现有配置生成），validate（检查结构）。

`when doctor`

针对当前项目运行所有 5 个 CLI 工具，并显示统一的健康报告卡。支持 --json 以获取机器可读的输出，支持 --watch 以通过实时仪表板进行持续监控。

`when watch`

后台守护进程，按间隔运行所有 5 个 CLI 工具，并将结果写入 ~/.whenlabs/status.json。为 Claude Code 状态栏集成提供支持。使用 --once 进行单次扫描，或使用 --interval <seconds> 自定义计划。

`when ci`

运行 stale、envalid 和 vow 检查——如果任何工具发现问题，则退出代码为 1。专为 CI 流水线设计：

when ci --ci         # GitHub Actions annotations (::error file=X::message)
when ci --json       # Machine-readable JSON output

GitHub Action

- uses: WhenLabs-org/when@main
  with:
    checks: stale,envalid,vow

卸载

npx @whenlabs/when uninstall

移除 MCP 服务器并清理 CLAUDE.md 指令。

许可证

MIT — 参见 LICENSE

由 Siddharth 在 WhenLabs 构建

WhenLabs/When