@whenlabs/when

Six tools. One install.

A single installable toolkit that brings six WhenLabs developer tools into your Claude Code / AI coding agent workflow. Once installed, all tools are available as MCP tools in every session — Claude uses them automatically when relevant.

Five tools (stale, envalid, berth, aware, vow) have CLI scan modes and run on a schedule. Velocity is the sixth tool — it is always-on and embedded (SQLite-backed), so it does not have a CLI scan mode and does not appear in doctor/watch/init/ci output.

Install

npx @whenlabs/when install

This is a one-time setup. After install, all six tools are available in every project you open with Claude Code.

What it does

Running npx @whenlabs/when install will:

1. Register a single MCP server (whenlabs) in your Claude Code configuration — all six tools, including velocity, are served from one server
2. Inject CLAUDE.md instructions so Claude knows when to use each tool automatically — and prefers them over shell commands
3. Clean up any legacy velocity-mcp registrations (velocity is now bundled)

Once connected, Claude can call any tool directly without you asking. For example, after a refactor Claude might run stale_scan to check for doc drift, or before a release it might run vow_check to validate licenses.

Proactive Background Scans

Tools run automatically in the background on a schedule and report findings in the Claude Code status line:

Tool	Interval	Status line
berth	15 min	ports:N — port conflicts found
stale	30 min	stale:N — docs drifted from code
envalid	30 min	env:N — .env validation issues
vow	60 min	lic:N? — unknown licenses found
aware	60 min	aware:stale — AI context files outdated

Only problems are shown — if everything is clean, the status line stays uncluttered. When Claude sees an issue in the status line, it proactively tells you and offers to fix it.

MCP Tools

These tools are available to Claude in every session after install:

MCP Tool	What it does
velocity_start_task	Start timing a coding task
velocity_end_task	End timing and record results
velocity_estimate	Estimate time for a planned task
velocity_stats	Show aggregate performance stats with insights
velocity_history	Show task history
stale_scan	Detect documentation drift
stale_fix	Auto-fix documentation drift (wrong paths, dead links, phantom env vars)
stale_auto_fix	Scan + auto-fix drift in one call
envalid_validate	Validate .env files against schemas
envalid_detect	Find undocumented env vars in codebase
envalid_generate_schema	Generate .env.schema from code analysis
envalid_auto_fix	Detect undocumented vars + auto-generate schema entries
berth_status	Show active ports and conflicts
berth_check	Scan project for port conflicts
berth_resolve	Auto-resolve port conflicts (kill or reassign)
berth_auto_resolve	Check + auto-resolve conflicts in one call
aware_init	Auto-detect stack, generate AI context files
aware_doctor	Diagnose project health and config issues
aware_auto_sync	Diagnose + auto-sync stale AI context files
vow_scan	Scan and summarize dependency licenses
vow_check	Validate licenses against policy
vow_hook_install	Install pre-commit license check hook

This table shows a highlights subset. Run when <tool> --help for all available commands per tool.

Cross-tool Intelligence

Tools automatically suggest follow-up actions when they detect issues relevant to other tools. For example, aware_init triggers a stale_scan when it generates new files, and envalid_detect suggests berth_register when it finds service URL env vars. These cascading suggestions surface as "Tip:" lines in tool output.

Multi-Editor Support

Install MCP

... View full README on GitHub