cavaleiro-ai/cavaleiro-agent-harness/codehealth-mcp
Claude Code and agent skill by cavaleiro-ai/cavaleiro-agent-harness
- community
Checking that the SKILL.md file is still in the repository.
Real-time structural Code Health via CodeScene MCP — review before edits, verify score deltas after changes, gate commits and PRs. Use when reviewing code quality, refactoring, checking if AI changes degraded a file, or before commit/PR.
Install
npx vskill@latest install cavaleiro-ai/cavaleiro-agent-harness/codehealth-mcpSKILL.md
Code Health MCP (CodeScene)
Structural maintainability feedback for AI-assisted coding. Complements style/lint skills (coding-standards, plankton-code-quality) with design-level health scores and regression gates.
Upstream: codescene-oss/codescene-mcp-server Package: @codescene/codehealth-mcp (stdio via npx)
Security and boundaries
Opt-in (ECC): The codescene block in mcp-configs/mcp-servers.json is a template only. ECC plugin installs do not auto-enable bundled MCP servers. Copy the entry into your config only if you want it. You can exclude it during ECC install/sync with ECC_DISABLED_MCPS=codescene,....
Credentials: No bundled token. Set CS_ACCESS_TOKEN yourself (see getting-a-personal-access-token.md in the upstream repo). Never commit tokens to the repo.
What the tools read: When invoked, tools analyze files and git state in the local repository you point them at (paths you pass, plus branch context for analyze_change_set). They do not run by themselves. For standalone mode, follow upstream privacy docs: codescene-mcp-server README and CodeScene policies. Do not use this skill for secrets, credentials, or paths you do not want analyzed.
If the MCP is unavailable (offline, bad token, server crash): Do not invent Code Health scores. Tell the user the check was skipped. Continue only with explicit user approval. Prefer lint/tests/verification-loop for gating when MCP is down. Re-enable checks once the server connects.
When to Use
- User asks to review code quality, refactor a file, or check if AI changes degraded maintainability
- Before editing a hotspot, legacy module, or unfamiliar file
- Before commit or pull request when you need a maintainability safeguard
- After a large agent-written diff — verify Code Health did not regress
- Pair with
verification-loop,tdd-workflow, or/quality-gateas a structural check (not a replacement for tests/lint)
When to Activate
Same triggers as When to Use above — this heading is what ECC uses for skill auto-activation.
How It Works
1. Connect the MCP server
Copy the codescene entry from mcp-configs/mcp-servers.json into your harness MCP config.
Claude Code (~/.claude.json → mcpServers):
Project-scoped: merge the same block into .mcp.json at the repo root.
Token setup is documented in the upstream repo (link above). Standalone mode does not require a paid CodeScene platform account for the four tools listed below. Restart the session and confirm the codescene server is connected before relying on scores.
2. Call standalone tools only
| Tool | When to use | |
|---|---|---|
code_health_review | Full structural analysis before modifying a file | |
code_health_score | Quick numeric score after each change (delta check) | |
pre_commit_code_health_safeguard | Block commits that introduce Code Health regressions | |
analyze_change_set | Branch-level check before opening a PR |
Do not call platform-only tools (e.g. repository-wide technical debt hotspot lists). Do not reference delta_analysis — not available on standalone.
3. Interpret scores (1–10)
| Range | Meaning | Agent behavior | |
|---|---|---|---|
| 9.0–10.0 | Green — healthy | Safer to extend; still prefer vertical slices | |
| 4.0–8.9 | Yellow — debt | Tread carefully; no drive-by refactors | |
| 1.0–3.9 | Red — severe debt | Narrow scope only |
4. Run the feedback loop
Before touching a file
- Run
code_health_reviewon the target path. - Record baseline score and listed code smells.
- Plan the smallest change that addresses the task.
Scope by score: below 5 — minimal diff only; 5–7 — no broad refactors; above 7 — safer to refactor, still verify after each edit.
After each change
- Run
code_health_scoreon the same file. - Compare to the baseline from
code_health_review. - If the score regressed, fix before continuing. Never mark the task done while the score is lower than when you started.
Before every commit — run pre_commit_code_health_safeguard on the repository path.
Before a PR — run analyze_change_set against the base branch (e.g. main).
Examples
Example: Flask maintainability improvement
On pallets/flask, an agent loop using only standalone tools:
code_health_reviewon a target module (baseline 4.82)- Targeted refactor addressing listed smells
code_health_scoreafter each editpre_commit_code_health_safeguardbefore commitanalyze_change_setbefore PR
Result: Code Health 4.82 → 9.1 (free standalone token only).
Example: AGENTS.md enforcement block
Paste into the project AGENTS.md or CLAUDE.md:
Example: anti-patterns vs correct loop
Pairing with ECC
| ECC skill / flow | Code Health MCP role | |
|---|---|---|
coding-standards | Style/naming; Code Health = structure/complexity | |
plankton-code-quality | Write-time lint/format; Code Health = pre/post edit structural gate | |
verification-loop / /quality-gate | Add structural regression check before "done" | |
security-review | Security vs maintainability — use both when relevant | |
tdd-workflow | Tests pass ≠ healthy design — check score after refactors |
Context tip: ECC recommends keeping MCP count low. Enable codescene when doing substantive edits; disable when not needed.
Related Skills
coding-standards— baseline conventionsplankton-code-quality— write-time lint/format hooksverification-loop— build/test/lint gatetdd-workflow— test-first developmentsecurity-review— security checklistdocumentation-lookup— library docs via Context7 (orthogonal)
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewNot runA model review is scheduled for the next rescan.
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/codehealth-mcp/SKILL.md
Popularity
- 7-day trend score
- 0
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/cavaleiro-ai/cavaleiro-agent-harness/codehealth-mcp)