@whenlabs/when

6가지 도구. 한 번의 설치.

Claude Code / AI 코딩 에이전트 워크플로우에 6가지 WhenLabs 개발자 도구를 통합하는 단일 설치형 툴킷입니다. 설치가 완료되면 모든 도구를 세션 내에서 MCP 도구로 사용할 수 있으며, Claude가 필요할 때 자동으로 호출합니다.

5가지 도구(stale, envalid, berth, aware, vow)는 CLI 스캔 모드를 지원하며 일정에 따라 실행됩니다. Velocity는 6번째 도구로, 항상 활성화되어 있고 내장(SQLite 기반)되어 있으므로 CLI 스캔 모드가 없으며 doctor/watch/init/ci 출력에 나타나지 않습니다.

설치

npx @whenlabs/when install

이 작업은 한 번만 수행하면 됩니다. 설치 후에는 Claude Code로 여는 모든 프로젝트에서 6가지 도구를 모두 사용할 수 있습니다.

기능

npx @whenlabs/when install을 실행하면 다음 작업이 수행됩니다:

Claude Code 설정에 단일 MCP 서버(whenlabs)를 등록합니다. velocity를 포함한 6가지 도구 모두 하나의 서버에서 제공됩니다.
CLAUDE.md 지침을 주입하여 Claude가 각 도구를 자동으로 사용하는 시점을 알 수 있게 하며, 셸 명령보다 도구를 우선적으로 사용하도록 합니다.
기존의 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를 제안합니다. 이러한 연쇄적인 제안은 도구 출력에 "Tip:" 라인으로 표시됩니다.

다중 에디터 지원

Claude Code 외에 다른 에디터에도 MCP 서버를 설치할 수 있습니다:

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 프로젝트 구성을 관리합니다. 6가지 도구 모두 별도의 구성 파일 대신 이 단일 파일에서 설정을 읽습니다. 하위 명령: 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 참조

WhenLabs의 Siddharth 제작

WhenLabs/When