Continuous Code Guardian

AI-powered continuous code assistant for Cursor IDE, VS Code, Antigravity, and Claude Code via MCP.

Overview

Focused public surface:

• /ca-checkit — evidence-ranked advisor (routing_cues + urgent|optional recommendations) → confirm subset (default prefers urgent) → run selected children (ca-aurait is never recommended; run it separately)
• /ca-smellit — quality-depth + architecture/clean-code prompt (ranked smell_scorecard, severity order) → proceed → apply → post-apply ran/skipped gate (for Sonar/CI gate prep use /ca-sonarit)
• /ca-testit — gap scorecard → merge/append into related non-empty tests when appropriate → ran/skipped verify (≤1 fix) → conditional coverit handoff for coverage focus or local misses
• /ca-commentit, /ca-docit, /ca-smellit — lightweight JS/TS export, JSDoc, surface, and smell heuristics (not full AST analysis)
• /ca-docit — structured companion markdown (canonical outline + API extract + drift scorecard) under docs/ → reconcile or report in sync (no comment edits)
• /ca-coverit — coverage readiness → local Cobertura/JSON/LCOV/Clover/Istanbul evidence when present → source-first proceed → source then tests → agent measure→iterate toward goal
• /ca-sonarit — Sonar/CI gate-prep helper → local SARIF/Sonar/GitLab/ESLint report evidence → source-first prompt → proceed → source then tests → optional report-driven improve→recheck (≤3 rounds; not a gate pass)
• /ca-aurait — Cognite Flows design-quality helper → scored prompt → confirm → apply design fixes

Polyglot support

All context packs accept UTF-8 text source files through an open suffix matrix. Go, Java, C#, and Dart have named heuristics; C++ and Scala have light heuristics; unknown but source-like files use the other generic profile. Flutter is detected as Dart and receives Flutter test/coverage guidance. These are advisory heuristics, not compiler or language-server analysis; see the Feature 026 quickstart.

Install

For end users installing this MCP into Cursor, VS Code, Antigravity, or Claude Code (Git, PyPI/uvx, local, or binary), see INSTALLATION.md.

Contributor / local editable install:

python -m pip install -e ".[dev]"
cp guardian.config.example.yaml guardian.config.yaml

Requires Python 3.12+. Optional analyzer CLIs (Ruff, ESLint, Semgrep, …) are only used when tools run with analyzer_mode=lint or all.

MCP tools

Tool (slash)	Purpose
/ca-checkit	Advisor: evidence-ranked plan from file cues → ask which to run (default prefers urgent) → invoke selected children; never recommends /ca-aurait
/ca-smellit	Quality-depth + architecture/clean-code prompt (smell_scorecard) → proceed → apply → post-apply ran/skipped gate; hand off Sonar/CI gate prep to /ca-sonarit
/ca-testit	Gap scorecard → focused-complete unit tests → ran/skipped verify (≤1 fix); coverit handoff for coverage goals
/ca-commentit	Ranked comment_scorecard → targeted comment plan (≤10) → proceed when non-empty → in-source comments only (no blanket refresh; not companion docs)
/ca-docit	Structured companion markdown (outline_contract + api_surface_extract + doc_drift_scorecard) under local docs/ with CAPITAL basename; in-sync skip rewrite; no comment edits
/ca-coverit	Coverage readiness → aspire-high + 80% floor → proceed → source then tests → agent measure→iterate (bounded rounds; MCP does not run coverage)
/ca-sonarit	Sonar/CI gate-prep helper (not Sonar / not gate-pass) → source-first prompt → proceed → source then tests → optional report-driven iterate (≤3 rounds; MCP does not run Sonar)
/ca-aurait	Flows design-quality helper → scored prompt (Q1–Q10 / 3.8+) → ask proceed → apply listed design fixes

How to use them in Cursor, VS Code, Antigravity, or Claude Code: HOW_TO_USE_TOOLS.md.

Slash autocomplete (/ca…) is installed automatically into the workspace — .cursor/commands/ in Cursor, .github/prompts/ in VS Code, .agent/workflows/ in Antigravity, .claude/commands/ in Claude Code — when the MCP server starts (requires "cwd": "${workspaceFolder}" in mcp.json, where supported). Obsolete older /ca-* shortcut files are removed on install, independently per editor.

Configuration

See guardian.config.example.yaml. Local guardian.config.yaml and .code-guardian/ are gitignored.

• smellit_max_excerpt_bytes / testit_max_excerpt_bytes / commentit_max_excerpt_bytes / docit_max_excerpt_bytes / coverit_max_excerpt_bytes / sonarit_max_excerpt_bytes / aurait_max_excerpt_bytes (default 65536)
• coverit_max_report_bytes / sonarit_max_report_bytes (default 65536); sonarit_max_related_files (default 4)
• smellit_analyzer_mode / testit_analyzer_mode / commentit_analyzer_mode / docit_analyzer_mode / coverit_analyzer_mode / sonarit_analyzer_mode / aurait_analyzer_mode (default none = fast)
• Optional analyzers: toggles for when analyzer_mode is lint or all
• Invalid config returns CONFIG_INVALID without leaking secrets

Validation

• Commentit scorecard & proceed gate: specs/021-commentit-scorecard-gate/quickstart.md
• Sonarit report-driven iterate: specs/020-sonarit-report-iterate/quickstart.md
• Smellit: specs/016-smellit-quality-depth/quickstart.md (also specs/013-smellit-architecture-refactor/quickstart.md)
• Testit: specs/017-testit-verify-loop/quickstart.md (also specs/004-testit-unit-tests/quickstart.md)
• Commentit / Docit split: specs/010-commentit-docit-split/quickstart.md
• Coverit iterate coverage: specs/015-coverit-iterate-coverage/quickstart.md
• Coverit max coverage: specs/014-coverit-max-coverage/quickstart.md
• Coverit / Sonarit source prep: specs/012-coverit-sonarit-source-prep/quickstart.md
• Aurait: specs/008-aurait-design-quality/quickstart.md

pytest -q

Spec Kit docs

• Feature 021: specs/021-commentit-scorecard-gate/
• Feature 020: specs/020-sonarit-report-iterate/
• Feature 017: specs/017-testit-verify-loop/
• Feature 016: specs/016-smellit-quality-depth/
• Feature 015: specs/015-coverit-iterate-coverage/
• Feature 014: specs/014-coverit-max-coverage/
• Feature 013: specs/013-smellit-architecture-refactor/
• Feature 012: specs/012-coverit-sonarit-source-prep/
• Feature 008: specs/008-aurait-design-quality/
• Feature 007: specs/007-coverit-coverage-prep/
• Feature 004: specs/004-testit-unit-tests/
• Feature 003: specs/003-smellit-cleanup-prompt/