{"id":48883095,"url":"https://github.com/whenlabs-org/when","last_synced_at":"2026-04-20T03:03:46.514Z","repository":{"id":351501065,"uuid":"1211161094","full_name":"WhenLabs-org/when","owner":"WhenLabs-org","description":"Six tools. One install. The WhenLabs developer toolkit.","archived":false,"fork":false,"pushed_at":"2026-04-15T10:01:32.000Z","size":2494,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T10:21:26.691Z","etag":null,"topics":["ai-tools","claude-code","cli","developer-tools","devex","mcp","npm-package","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WhenLabs-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"patreon":"WhenSid"}},"created_at":"2026-04-15T06:00:17.000Z","updated_at":"2026-04-15T10:01:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/WhenLabs-org/when","commit_stats":null,"previous_names":["whenlabs-org/when"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/WhenLabs-org/when","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhenLabs-org%2Fwhen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhenLabs-org%2Fwhen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhenLabs-org%2Fwhen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhenLabs-org%2Fwhen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WhenLabs-org","download_url":"https://codeload.github.com/WhenLabs-org/when/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WhenLabs-org%2Fwhen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31870516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"online","status_checked_at":"2026-04-16T02:00:06.042Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","claude-code","cli","developer-tools","devex","mcp","npm-package","typescript"],"created_at":"2026-04-16T04:01:02.688Z","updated_at":"2026-04-16T04:01:04.189Z","avatar_url":"https://github.com/WhenLabs-org.png","language":"TypeScript","funding_links":["https://patreon.com/WhenSid"],"categories":[],"sub_categories":[],"readme":"# @whenlabs/when\n\n**Six tools. One install.**\n\nA 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.\n\nFive 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.\n\n## Install\n\n```bash\nnpx @whenlabs/when install\n```\n\nThis is a one-time setup. After install, all six tools are available in every project you open with Claude Code.\n\n## What it does\n\nRunning `npx @whenlabs/when install` will:\n\n1. Register a **single MCP server** (`whenlabs`) in your Claude Code configuration — all six tools, including velocity, are served from one server\n2. Inject **CLAUDE.md instructions** so Claude knows when to use each tool automatically — and prefers them over shell commands\n3. Clean up any legacy `velocity-mcp` registrations (velocity is now bundled)\n\nOnce 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.\n\n## Proactive Background Scans\n\nTools run automatically in the background on a schedule and report findings in the Claude Code status line:\n\n| Tool | Interval | Status line |\n|------|----------|-------------|\n| berth | 15 min | `ports:N` — port conflicts found |\n| stale | 30 min | `stale:N` — docs drifted from code |\n| envalid | 30 min | `env:N` — .env validation issues |\n| vow | 60 min | `lic:N?` — unknown licenses found |\n| aware | 60 min | `aware:stale` — AI context files outdated |\n\nOnly 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.\n\n## MCP Tools\n\nThese tools are available to Claude in every session after install:\n\n| MCP Tool | What it does |\n|---|---|\n| `velocity_start_task` | Start timing a coding task |\n| `velocity_end_task` | End timing and record results |\n| `velocity_estimate` | Estimate time for a planned task |\n| `velocity_stats` | Show aggregate performance stats with insights |\n| `velocity_history` | Show task history |\n| `stale_scan` | Detect documentation drift |\n| `stale_fix` | Auto-fix documentation drift (wrong paths, dead links, phantom env vars) |\n| `stale_auto_fix` | Scan + auto-fix drift in one call |\n| `envalid_validate` | Validate .env files against schemas |\n| `envalid_detect` | Find undocumented env vars in codebase |\n| `envalid_generate_schema` | Generate .env.schema from code analysis |\n| `envalid_auto_fix` | Detect undocumented vars + auto-generate schema entries |\n| `berth_status` | Show active ports and conflicts |\n| `berth_check` | Scan project for port conflicts |\n| `berth_resolve` | Auto-resolve port conflicts (kill or reassign) |\n| `berth_auto_resolve` | Check + auto-resolve conflicts in one call |\n| `aware_init` | Auto-detect stack, generate AI context files |\n| `aware_doctor` | Diagnose project health and config issues |\n| `aware_auto_sync` | Diagnose + auto-sync stale AI context files |\n| `vow_scan` | Scan and summarize dependency licenses |\n| `vow_check` | Validate licenses against policy |\n| `vow_hook_install` | Install pre-commit license check hook |\n\n\u003e This table shows a highlights subset. Run `when \u003ctool\u003e --help` for all available commands per tool.\n\n### Cross-tool Intelligence\n\nTools 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.\n\n## Multi-Editor Support\n\nInstall MCP servers into other editors alongside Claude Code:\n\n```bash\nnpx @whenlabs/when install --cursor     # Cursor\nnpx @whenlabs/when install --vscode     # VS Code\nnpx @whenlabs/when install --windsurf   # Windsurf\nnpx @whenlabs/when install --all        # All supported editors\n```\n\nWithout flags, `install` targets Claude Code only.\n\n## CLI Usage\n\nYou can also run tools directly from the command line:\n\n```bash\nwhen init            # Onboard a project — bootstrap configs, run all tools, auto-fix\nwhen config          # Show unified .whenlabs.yml config\nwhen config init     # Generate .whenlabs.yml from existing tool configs\nwhen config validate # Validate config structure\nwhen stale scan\nwhen stale fix       # Auto-fix documentation drift\nwhen envalid validate\nwhen envalid detect --generate  # Generate schema from code\nwhen berth status\nwhen berth resolve   # Auto-resolve port conflicts\nwhen aware init\nwhen vow scan\nwhen vow hook install  # Install pre-commit license hook\nwhen status          # Show installation status\nwhen doctor          # Run all tools, show unified health report\nwhen doctor --watch  # Continuous monitoring dashboard\nwhen watch           # Background daemon for status line\nwhen ci              # Run checks for CI (exits 1 on issues)\n```\n\n### `when init`\n\nOne command to fully onboard any project:\n1. **Bootstrap** — creates `.env.schema`, `.vow.json`, `.stale.yml`, and registers berth ports based on your project\n2. **Scan** — runs all 5 CLI tools in parallel\n3. **Auto-fix** — automatically fixes stale drift if detected\n4. **Config** — generates a unified `.whenlabs.yml` from the bootstrapped configs\n\n### `when config`\n\nManage 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).\n\n### `when doctor`\n\nRuns 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.\n\n### `when watch`\n\nBackground 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 \u003cseconds\u003e` to customize the schedule.\n\n### `when ci`\n\nRuns stale, envalid, and vow checks — exits 1 if any tool finds issues. Designed for CI pipelines:\n\n```bash\nwhen ci --ci         # GitHub Actions annotations (::error file=X::message)\nwhen ci --json       # Machine-readable JSON output\n```\n\n### GitHub Action\n\n```yaml\n- uses: WhenLabs-org/when@main\n  with:\n    checks: stale,envalid,vow\n```\n\n## Uninstall\n\n```bash\nnpx @whenlabs/when uninstall\n```\n\nRemoves the MCP server and cleans up CLAUDE.md instructions.\n\n## License\n\nMIT — see [LICENSE](./LICENSE)\n\n---\n\nBuilt by [Siddharth](https://github.com/Caissaisdead) at [WhenLabs](https://github.com/WhenLabs-org)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhenlabs-org%2Fwhen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwhenlabs-org%2Fwhen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwhenlabs-org%2Fwhen/lists"}