{"id":51133821,"url":"https://github.com/nellcorp/codehealth","last_synced_at":"2026-06-25T15:30:50.284Z","repository":{"id":354607373,"uuid":"1221888048","full_name":"nellcorp/codehealth","owner":"nellcorp","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-11T06:25:56.000Z","size":113,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-11T07:27:49.365Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nellcorp.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":null,"dco":null,"cla":null}},"created_at":"2026-04-26T20:05:37.000Z","updated_at":"2026-05-11T06:25:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nellcorp/codehealth","commit_stats":null,"previous_names":["nellcorp/codehealth"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/nellcorp/codehealth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nellcorp%2Fcodehealth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nellcorp%2Fcodehealth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nellcorp%2Fcodehealth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nellcorp%2Fcodehealth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nellcorp","download_url":"https://codeload.github.com/nellcorp/codehealth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nellcorp%2Fcodehealth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34781486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"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":[],"created_at":"2026-06-25T15:30:49.256Z","updated_at":"2026-06-25T15:30:50.278Z","avatar_url":"https://github.com/nellcorp.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# codehealth\n\nPortable Go binary that exposes [CodeScene](https://codescene.io) and\n[Codecov](https://codecov.io) tooling to [Claude Code](https://claude.ai/code)\n(and any MCP client) plus a matching CLI suitable for Git hooks and CI.\n\nThe binary speaks two protocols:\n\n- **MCP** (`codehealth serve`) — stdio transport, registered in\n  `.mcp.json`. Claude calls the tools below to read project health,\n  coverage, hotspots, and validate refactors before commit.\n- **CLI** (`codehealth \u003csubcommand\u003e`) — same backends, exit-status\n  output, used by pre-commit hooks and shell scripts.\n\n\u003e **Migrating from `codescene-mcp` v0.1.x?** Binary + module renamed to\n\u003e `codehealth` in v0.2.0. Update `.mcp.json`'s `command` to\n\u003e `codehealth` and re-run `go install github.com/nellcorp/codehealth/cmd/codehealth@latest`.\n\u003e All existing CodeScene tool names (`health_overview`, `file_health`, …) are unchanged.\n\n## Tools\n\n| Tool | Source | Purpose |\n|---|---|---|\n| `health_overview` | CodeScene REST API | Live hotspot + average score; compared against the local `.codescene-thresholds` floor. |\n| `list_hotspots` | CodeScene REST API | Top-N files by churn × complexity. |\n| `file_health` | CodeScene REST API | Score + biomarkers for one repo-relative path. |\n| `component_health` | CodeScene REST API | Architectural-component health from the latest analysis. |\n| `list_code_reviews` | CodeScene REST API | Recent CodeScene Code Reviews (delta-analyses) the PR integration ran. |\n| `code_review` | CodeScene REST API | One Code Review by id — per-file before/after `code_health`, failed gates, commits. |\n| `kpi_trend` | CodeScene REST API | 4-factors dashboard trend line (`code-health`, `delivery`, `knowledge`, `team-code-alignment`). |\n| `delta_check` | Local: `cs` CLI or gocyclo+gocognit | Scores staged or specified files vs HEAD. Use **before** committing. Pass `strict: true` to fail when `cs` is missing instead of falling back. |\n| `score_file` | Local: same as above | One-file complexity probe. Pass `strict: true` to fail when `cs` is missing. |\n| `coverage_overview` | Codecov REST API | Project coverage % vs the local `.codecov-thresholds` floor. |\n| `file_coverage` | Codecov REST API | Per-file coverage at a branch or commit SHA. |\n| `delta_coverage` | Codecov REST API | Coverage delta between two commits. Use **before** pushing/PR. |\n\nCodeScene API tools require `CODESCENE_TOKEN` and `CODESCENE_PROJECT_ID`.\nCodecov tools require `CODECOV_TOKEN` and `CODECOV_REPO`. Local CodeScene\ntools work without credentials. Each backend degrades independently —\nconfiguring only one is fine.\n\n### Two scoring paths (CodeScene)\n\n| Code state | Mechanism | Engine |\n|---|---|---|\n| Pushed and analyzed by CodeScene | REST API client (built into binary) | Authoritative — matches the CI gate. |\n| Local working tree / staged | Shell out to CodeScene `cs` CLI when present; pure-Go fallback (gocyclo + gocognit) otherwise | Approximate when falling back; signals can disagree with CI. |\n\nThe CodeScene REST API only scores code that has been pushed and\nanalysed. Local scoring exists to give a pre-commit signal — Claude can\nask \"did this change make the file healthier?\" without waiting for a\npost-push reanalysis. When `cs` is missing the binary prints a one-line\nwarning to stderr and falls back to the Go heuristic; CI remains the\nauthoritative gate.\n\nCodecov has only one path — the REST API — because coverage requires an\nuploaded report from CI.\n\n## Integrating into your repo\n\nFor a complete drop-in recipe — `.mcp.json`, Lefthook hook, Makefile targets,\nslash commands, CI gate, ADR template, two-phase rollout — see the\n[**Integration Playbook**](docs/integration-playbook.md).\n\n## Installation\n\n### Pre-built binary\n\nDownload from [Releases](https://github.com/nellcorp/codehealth/releases)\nor:\n\n```bash\ngo install github.com/nellcorp/codehealth/cmd/codehealth@latest\n```\n\n### Optional: install CodeScene `cs` CLI\n\nFor engine-accurate local scoring, install the [CodeScene CLI](https://codescene.io/docs/guides/cli/index.html).\nThe binary auto-detects `cs` on PATH; without it the pure-Go fallback runs.\n\n## Configuration\n\n```bash\n# CodeScene\nexport CODESCENE_TOKEN=...                          # required for CodeScene API tools\nexport CODESCENE_PROJECT_ID=12345                   # required for CodeScene API tools\nexport CODESCENE_URL=https://api.codescene.io       # default\nexport CS_CLI_PATH=cs                               # default\n\n# Codecov\nexport CODECOV_TOKEN=...                            # required for Codecov tools\nexport CODECOV_REPO=github/nellcorp/codehealth      # required: service/owner/repo\nexport CODECOV_URL=https://api.codecov.io           # default\n```\n\n`CODECOV_REPO` is a single slug — copy from the Codecov UI URL. `service`\nis one of `github`, `github_enterprise`, `gitlab`, `gitlab_enterprise`,\n`bitbucket`, `bitbucket_server`.\n\n### Threshold files\n\nTwo optional dotfiles. Missing files are treated as \"no floor\".\n\n`.codescene-thresholds`:\n```\nHOTSPOT_THRESHOLD=9.0\nAVERAGE_THRESHOLD=8.5\n```\n\n`.codecov-thresholds`:\n```\nCOVERAGE_THRESHOLD=80.0\nCOVERAGE_DELTA_THRESHOLD=-0.5\n```\n\n`COVERAGE_DELTA_THRESHOLD` is the maximum allowed coverage drop in\npercentage points (negative = tolerated drop, e.g. `-0.5` allows up to\n0.5pp regression).\n\n### Claude Code (`.mcp.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"codehealth\": {\n      \"command\": \"codehealth\",\n      \"args\": [\"serve\"],\n      \"env\": {\n        \"CODESCENE_URL\": \"https://api.codescene.io\",\n        \"CODESCENE_TOKEN\": \"${CODESCENE_TOKEN}\",\n        \"CODESCENE_PROJECT_ID\": \"12345\",\n        \"CODECOV_TOKEN\": \"${CODECOV_TOKEN}\",\n        \"CODECOV_REPO\": \"github/nellcorp/codehealth\"\n      }\n    }\n  }\n}\n```\n\n### Lefthook (`lefthook.yml`)\n\nWarn-only pre-commit gate; CI remains authoritative.\n\n```yaml\npre-commit:\n  commands:\n    codehealth-delta:\n      glob: \"*.go\"\n      run: |\n        if ! command -v codehealth \u003e/dev/null; then\n          exit 0\n        fi\n        codehealth delta --staged || true\n```\n\nBlocking gate (fails the commit when the `cs` CLI is not installed, so\nthe gocyclo+gocognit fallback's narrower smell taxonomy never masks a\nCodeScene biomarker like Bumpy Road or Complex Method):\n\n```yaml\npre-commit:\n  commands:\n    codehealth-delta:\n      glob: \"*.go\"\n      run: codehealth delta --staged --strict\n```\n\n`--strict` only controls engine selection; regression policy stays\nwarn-only because CI is the authoritative gate.\n\n## CLI reference\n\n```bash\ncodehealth serve                              # MCP server (stdio)\ncodehealth health                             # CodeScene project scores + floor\ncodehealth delta [--staged] [--strict] [paths] # local delta vs HEAD (warn-only; --strict fails if `cs` is missing)\ncodehealth hotspots --limit 10                # CodeScene top hotspots\ncodehealth file \u003cpath\u003e                        # CodeScene file health + biomarkers\ncodehealth components                         # architectural-component health\ncodehealth list-code-reviews [--page]         # CodeScene Code Reviews (delta-analyses)\ncodehealth code-review \u003cid\u003e                   # one Code Review by id\ncodehealth kpi-trend \u003cfactor\u003e [kpi]           # 4-factors dashboard trend line\ncodehealth coverage                           # Codecov project coverage + floor\ncodehealth coverage-file \u003cpath\u003e [--ref \u003cr\u003e]   # Codecov per-file coverage\ncodehealth coverage-delta \u003cbase\u003e \u003chead\u003e       # Codecov compare base..head\n```\n\n## Development\n\n```bash\ngo build ./...\ngo test ./...\ngo vet ./...\ngoreleaser release --snapshot --clean   # local multi-OS build\n```\n\nReleases are cut by tagging `vX.Y.Z`. The `release.yaml` workflow runs\nGoReleaser and publishes archives + checksums.\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnellcorp%2Fcodehealth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnellcorp%2Fcodehealth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnellcorp%2Fcodehealth/lists"}