Agent Code Guard

Deterministic maintainability guardrails for source code and Markdown changed by a human or coding agent.

Agent Code Guard measures file size, callable size, structural nesting, cyclomatic complexity, Markdown document size, and Markdown section size. It reports deterministic PASS, REVIEW, or FAIL results without rewriting your files.

It complements rather than replaces tests, compilers, linters, formatters, security tools, and design judgment.

Why it is useful

Code Guard surfaces files and callables that are becoming difficult to review, deep nesting and complex decision logic, and Markdown specifications that are losing navigability. It gives humans and agents the same repeatable review point after edits and can prevent silent LOC growth beyond an explicit project policy.

What humans gain

• Consistent signals across supported languages and Markdown, whether a change came from a person or an agent.
• A shared PASS/REVIEW/FAIL vocabulary: continue, inspect with judgment, or block pending correction or an authorized exception.
• The same checks locally and in CI, with no configuration required for ordinary use and no automatic source mutation.

What agents gain

• Deterministic feedback after edits and consistent process exits.
• Changed-file scope instead of unnecessary full-repository scans.
• Compact JSON that omits normalized pass noise while retaining actionable findings and result structure.
• Named required policies, so only relevant guidance needs to be loaded, plus a version-matched bundled skill with REVIEW-judgment and anti-gaming rules.

This workflow is designed to reduce unnecessary output and policy loading. It still requires the source context needed to understand and judge each finding; it makes no claim about measured token savings.

Installation

pipx isolates the command from project environments:

pipx install agent-code-guard
code-guard --version
code-guard doctor

--version confirms the installed distribution identity. doctor checks the active installation's health. See the usage guide for virtual environment, uv, and developer alternatives.

Ask your agent to adopt it

Copy this prompt to a coding agent:

Adopt Agent Code Guard for this repository using the official project and documentation at https://github.com/stef-k/agent-code-guard. This prompt authorizes installing the published distribution in an isolated supported way, preferably with pipx install agent-code-guard, and persistently activating or exporting its installed, version-matched skill for the current agent environment. Verify code-guard --version and run code-guard doctor, then locate the skill with code-guard --skill-path. Follow the skill activation guide: activate that installed path when the platform supports it, or export it with code-guard --export-skill <target-directory> to the platform's documented skill directory. Do not guess a target or overwrite an existing export; verify that .agent-code-guard-version matches the installed distribution. Follow the agent workflow without creating a LOC baseline. After meaningful source or Markdown edits, run code-guard . --changed-only --json --json-mode compact; outside Git, pass the exact edited files. Inspect REVIEW and FAIL findings, make only genuine improvements, rerun the check, and report the result. Never weaken thresholds, exclusions, configuration, or baselines merely to silence findings. Code Guard does not install or enable hooks by default. Ask before configuring a post-edit or post-turn hook, or making unrelated persistent agent or platform changes. Finish by reporting the installed version, doctor status, activated skill location, first analysis result, and any REVIEW findings you accepted.

Five-minute start

From a Git worktree, inspect the current change:

code-guard . --changed-only

Git supplies the changed candidates; every enabled and applicable guard runs. No configuration is needed. A REVIEW asks for inspection and judgment, not an automatic refactor. Outside Git, pass the exact edited files instead, such as code-guard src/app.py docs/guide.md.

See the agent workflow guide for repeated human and agent use.

Recommended workflow

edit supported code or Markdown
        ↓
run Code Guard on changed scope
        ↓
PASS → continue
REVIEW → inspect, justify or genuinely improve
FAIL → fix or obtain an explicitly authorized exception
        ↓
rerun
        ↓
report the result before completion

Use code-guard . --changed-only --json --json-mode compact for a structured, low-noise manual agent check. Hooks are optional, platform-owned, and require user authorization; Code Guard does not install them. The workflow guide owns the complete manual and hook-assisted process.

Interpreting results

• PASS — no special action; exit 0.
• REVIEW — inspect and decide whether genuine structural improvement is warranted; normally exit 1.
• Completed FAIL — blocks normal completion until fixed or an explicitly authorized exception applies; exit 2 with a completed report on stdout.
• INCOMPLETE — one or more requested syntax analyses are unavailable; independent completed findings remain authoritative, but the run exits 3.
• An argparse usage or invalid-choice error exits 2, writes usage/error text to stderr, and produces no completed report.
• Other Code Guard tool, configuration, scope, or unexpected errors exit 3.

--ci makes REVIEW nonblocking at the process level by changing its exit to 0; it does not hide findings or change FAIL, INCOMPLETE, and tool-error exits.

Never game a metric. Do not create artificial helpers, files, abstractions, formatting, exclusions, or policy changes merely to lower a measurement. A REVIEW is not proof of a defect or a mandatory refactor.

Guard reference

Comparisons are strictly greater-than, so equality passes. All guards except file LOC are REVIEW-only; only file LOC can FAIL. A new guard must provide distinct, deterministic value rather than duplicate conventional tooling. See Guard admission.

Result and JSON reference

Every completed analysis reports selected, analyzed, inapplicable, and all-guard-excluded file counts. Bare --json is the compatible full output; --json-mode debug is byte-identical for the same completed invocation, while --json-mode compact removes only normalized pass findings and retains the result, scope, required policies, guards, ordering, and actionable findings. Named modes require --json. See Usage for the schema and option contract.

Known per-file syntax or provider failures instead produce overall: "incomplete", ordered structured unavailable records, and completed guard evidence. Syntax guards identify unavailable paths; LOC and Markdown remain complete. Full, debug, and compact JSON retain unavailable records unchanged, and completed runs retain their existing schema.

Common scope commands

# Current Git work
code-guard . --changed-only

# Pull request or branch comparison
code-guard . --base-ref origin/main --ci

# Deliberate full audit
code-guard .

The base ref must exist in the chosen environment. Changed work is not a full audit; do not repeatedly scan unrelated files after every edit.

Supported languages and formats

Syntax guards support Python, Go, Kotlin, C#, Java, JavaScript, TypeScript, JSX, TSX, Vue JavaScript/TypeScript script regions, C++, Rust, PHP, Swift, and Dart. Markdown guards apply to .md files.

Generic .h files are not syntax-dispatched; .markdown is not enabled; Vue template and style regions are not executable syntax input; and unsupported artifacts are inapplicable. Malformed applicable syntax or a required provider failure is unavailable evidence, distinct from both an inapplicable file and a completed FAIL finding. See Language support.

Skill integration

An installed distribution includes the matching Code Guard skill payload:

code-guard --skill-path
code-guard --export-skill <target-directory>

Skill activation is platform-specific and is not performed by pipx or Code Guard. See Skill distribution. The checkout compatibility runner is for repository development, not normal installation.

Configuration

Built-in defaults require no configuration. Configure a project only for a concrete policy reason; see the configuration guide. The LOC baseline is an explicit adoption tool for established legacy repositories, not an ordinary-use requirement or a way to silence findings. Its default ratchetAt: "fail" policy freezes files above failAt; choose ratchetAt: "review" only when every established file above warnAt must be non-increasing while ordinary findings in that range remain REVIEW.

Trust, CI, and platform support

CI installs Agent Code Guard and analyzes its own real checkout. REVIEW findings remain visible but non-blocking, while FAIL findings and tool errors block the workflow; the repository intentionally uses no LOC baseline.

The maintained interpreter range is CPython 3.10–3.14. See Platform support for supported binary platforms and source-build boundaries.

Documentation

• Documentation index
• Agent workflow
• Usage and CLI reference
• Configuration
• Language support
• Platform support
• Skill distribution

Feedback, security, and license

Report defects through the bug report form, propose measurements through the candidate guard form, and follow the security policy for vulnerabilities.

Agent Code Guard grew from the Agent LOC Guard prototype and is now the canonical implementation. Licensed under the MIT License.