Agent Code Guard

Deterministic guardrails for agent-assisted software development.

Code Guard gives coding agents objective measurements and PASS / REVIEW / FAIL signals while leaving design decisions to agent and user judgment.

deterministic measurement
        ↓
PASS / REVIEW / FAIL
        ↓
agent judgment

Installation

pipx keeps the command isolated from project environments:

pipx install agent-code-guard

See the usage guide for a virtual-environment alternative and developer installation.

Quick start

Run all enabled, applicable guards over your current Git work:

code-guard . --changed-only

Git determines the edited-file candidates, Code Guard applies every enabled and applicable guard, and project or user exclusions remain authoritative. No configuration file is required.

Result model

• PASS — no special action.
• REVIEW — inspect the finding and decide whether meaningful improvement is warranted. REVIEW is not automatic refactoring.
• FAIL — blocks normal completion until fixed or an explicitly authorized exception applies.

Never game the metric. Preserve clarity and useful structure; do not create artificial helpers, files, abstractions, formatting, or exclusions merely to lower a measurement.

Default guards

Comparisons are strictly greater-than, so equality passes. All guards except file LOC are REVIEW-only; only file LOC can FAIL.

Agent Code Guard intentionally remains small. A new guard must provide distinct, deterministic agent-guardrail value rather than merely duplicate mature conventional tooling. See Guard admission.

Common workflows

Normal Git work:

code-guard . --changed-only

Explicit agent-owned scope without Git:

code-guard src/Foo.py src/Bar.ts docs/guide.md

Pull request or branch comparison:

code-guard . --base-ref origin/main --ci

The actual base ref must exist or be fetched correctly in the chosen CI environment.

Deliberate full audit:

code-guard .

Changed work is not a full audit. Use Git selection during normal development; do not repeatedly scan unrelated repository history 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.

Important boundaries:

• Generic .h files are not syntax-dispatched because their language context is ambiguous.
• .markdown is not currently enabled for Markdown guards.
• Vue template and style regions are not executable syntax input.
• Unsupported artifacts are simply inapplicable.
• Malformed applicable syntax or a required provider failure is a fail-closed tool error, never heuristic partial analysis.

See Language support for extension and mixed-content details.

Agent integration

CLI-only use requires no skill export. Each installed distribution also carries a version-matched Code Guard skill payload for agent workflows:

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

See Skill distribution for discovery, export, and integration guarantees. The checkout compatibility runner is for repository and skill compatibility, not primary end-user installation.

Configuration

Built-in defaults require no config. A minimal project configuration is:

{
  "version": 1
}

Use configuration only when a project has a concrete policy reason to change a guard or scope. See the Configuration guide.

Documentation

• Documentation index
• Usage
• Configuration
• Language support
• Platform support
• Skill distribution

Platform support

The maintained interpreter range is CPython 3.10–3.14. The normal binary installation envelope is:

• Windows x86-64 and ARM64;
• macOS x86-64 and ARM64;
• Linux glibc 2.34 or newer on x86-64 and ARM64.

Source builds outside that binary envelope are best effort and are not release-supported. See Platform support for exact wheel and deployment boundaries.

Feedback and security

Report normal defects through the bug report form and propose new measurements through the Candidate guard form. For vulnerability reporting, follow the repository Security policy.

Background and license

Agent Code Guard grew from the Agent LOC Guard prototype and is now the canonical implementation. It remains focused on deterministic measurements that complement—not replace—tests, compilers, formatters, linters, security tools, or design judgment.

Licensed under the MIT License.