@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:

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:

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 servers into other editors alongside 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

Without flags, install targets Claude Code only.

CLI Usage

You can also run tools directly from the command line:

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

One command to fully onboard any project:

1. Bootstrap — creates .env.schema, .vow.json, .stale.yml, and registers berth ports based on your project

2. Scan — runs all 5 CLI tools in parallel

3. Auto-fix — automatically fixes stale drift if detected

4. Config — generates a unified .whenlabs.yml from the bootstrapped configs

when config

Manage the unified .whenlabs.yml project config. All six tools read their settings from this single file instead of separate config files. Subcommands: init (generate from existing configs), validate (check structure).

when doctor

Runs all 5 CLI tools against the current project and displays a unified health report card. Supports --json for machine-readable output and --watch for continuous monitoring with a live dashboard.

when watch

Background daemon that runs all 5 CLI tools on intervals and writes results to ~/.whenlabs/status.json. Powers the Claude Code status line integration. Use --once for a single scan or --interval <seconds> to customize the schedule.

when ci

Runs stale, envalid, and vow checks — exits 1 if any tool finds issues. Designed for CI pipelines:

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

Uninstall

npx @whenlabs/when uninstall

Removes the MCP server and cleans up CLAUDE.md instructions.

License

MIT — see LICENSE

Built by Siddharth at WhenLabs