Skip to main content

AgentGuard

AI-native quality gate for agent-generated code.
Scan · Audit · Auto-fix · Track trends

Features • Quick Start • Commands • Demo • Rules • Custom Rules

CI PyPI License Stars Python Version


🚀 Install in 3 seconds

pip install agentguard-tool
cd your-project
gate run

Done. AgentGuard scans your code, detects AI-specific issues (hardcoded secrets, unsafe APIs, hallucinations), auto-fixes what it can, and tracks quality trends over time.


Why AgentGuard?

Traditional linters like SonarQube and CodeQL were built for human-written code. AI agents write code differently — they hallucinate module names, leave placeholder comments, generate giant functions, and introduce patterns that human linters miss.

AgentGuard is built for the age of AI-generated code.

It understands the patterns, pitfalls, and security risks specific to code written by LLMs. It runs as a CI-ready CLI, a pre-commit hook, or a daily cron.


Features

🔍 AI-Specific Detection (17 rules)

Category Rules Severity
Security unsafe_api, secret_leak, sql_injection, path_traversal 🚫 BLOCKER
Python Quality bare_except, ruff_blocker, ruff_fixable, syntax_check, exception_quality, mutable_defaults, compare_with_is 🔧 FIXABLE
Code Smells placeholder_check, ai_hallucination, performance, hardcoded_paths 🔧 FIXABLE
Config & Logging hardcoded_config, logging_quality ℹ️ INFO

Each rule is a standalone Python class. Plug-in architecture: add a file, add a decorator.

⭐ Quality Score (v6.0 NEW)

After every scan, AgentGuard calculates a 0-100 quality score across 5 dimensions:

Dimension Weight Measures
Blocker Rate 25% Zero blockers = 100, 5+ = 0
Fix Rate 25% % of fixable issues actually fixed
Coverage 15% Scan completeness
Security 20% Safety issues found
Trend 15% Improving or regressing?

Output: 🟢 Grade: A (Score: 97.6/100)

🛡️ Suppression System (v6.0 NEW)

Silence false positives inline — works like SonarQube's // NOSONAR:

eval(user_input)  # gate:ignore unsafe_api  # this is safe here
os.system(cmd)    # gate:ignore-start unsafe_api
# ... range of code to suppress ...
                  # gate:ignore-end unsafe_api

🧪 Test Generation (v6.0 NEW)

Automatically generates pytest skeletons for changed files:

# From: src/parser.py → generates: tests/test_parser.py
def test_parse():
    """Test parse function"""
    result = parse(mock_input=None)
    assert result is not None

📊 Agent Behavior Audit

Reads agent trace data and produces a daily report:

  • Tool call frequency & ranking
  • Error rate & anomaly detection
  • Token consumption & cost estimates
  • Model usage distribution

📈 Trend Dashboard

Text-based trend chart with zero external dependencies:

━━━ 📈 Quality Trend (Last 14 days) ━━━
  05/08 ████████████████   0 issues  ✅
  05/09 ████████████░░░░   3 issues  ⚠️
  05/10 ████████████████   0 issues  ✅

Data persists in SQLite. View anytime with gate trend.

🔧 Auto-Fix Pipeline

Automatically fixes what it can, backed up and git-committed:

  • Unused imports (F401) and variables (F841)
  • Bare except: → except Exception:
  • Hardcoded paths → $HOME references
  • Ruff-safe auto-fixes

🧩 Plugin Rule Architecture

Rules are Python classes. Adding a new rule = one file, one class, one decorator.

@register_rule
class MyRule(Rule):
    name = "my_rule"
    severity = Severity.BLOCKER

    def diagnose(self, filepath: str) -> list[Issue]:
        # Your detection logic here
        ...

Quick Start

# 🎯 Scan your project
pip install agentguard-tool
cd your-project
gate run

# 🔍 Quick check (staged files only)
gate run --quick

# 📊 Agent behavior audit
gate audit

# 📈 View quality trends
gate trend

# 🔧 Install pre-commit hooks
gate install

Run from source

git clone https://github.com/weijinsheng123456/agentguard.git
cd agentguard
python gate.py run

Demo

Terminal recording of a realistic gate run session:

$ gate run
2026-05-18 09:42:11,238 [INFO] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2026-05-23 22:06:12,827 [INFO]   AgentGuard v6.0.0 — Full scan
2026-05-18 09:42:11,238 [INFO] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2026-05-18 09:42:11,271 [INFO] 📦 共 42 个 .py 文件
2026-05-18 09:42:11,271 [INFO] 🆕 新增: 2  |  ✏️ 修改: 5  |  ✅ 稳定: 35
2026-05-18 09:42:11,279 [INFO] 引擎加载 8 条规则: (6 文件级 + 2 目录级)
2026-05-18 09:42:11,414 [INFO]   目录级规则: 2 个问题
2026-05-18 09:42:11,438 [INFO]   文件级规则: 3 个问题
2026-05-18 09:42:11,438 [INFO] 🔴 BLOCKER: 2  |  🟡 FIXABLE: 2  |  🔵 INFO: 1
2026-05-18 09:42:11,438 [WARNING] ⚠️  有 BLOCKER 问题,跳过自动修复
2026-05-18 09:42:11,438 [INFO] 🔍 全量关键项扫描...
2026-05-18 09:42:11,481 [INFO] 📊 运行Agent行为审计...

━━━ ⚠️ 质量门禁 05/18 ━━━
扫描: 42 个文件(+2/~5)
阻塞: 2 项 ❌ 需人工
  ❌ src/agent/tools.py:L18  UNSAFE_SYSTEM
  ❌ src/config.py:L7  LEAK_SECRET

━━━ 🤖 Agent行为审计 (7天) ━━━
Tool调用: 128 次
错误率: 2.3% ✅
Token消耗: 184,320
Top工具: edit, shell, read_file

Screenshots

Trend dashboard output from gate trend:

$ gate trend
━━━ 📈 质量门禁趋势 (最近14天) ━━━
  05-05 ████░░░░░░░░░░░░   3问题 修2 ✅
  05-06 ██████████░░░░░░   7问题 修4 ❌1 ❌
  05-07 ██░░░░░░░░░░░░░░   1问题 ✅
  05-08 █░░░░░░░░░░░░░░░   0问题 ✅
  05-09 ███████░░░░░░░░░   5问题 修3 ⚠️
  05-10 █░░░░░░░░░░░░░░░   0问题 ✅
  05-11 ███░░░░░░░░░░░░░   2问题 修2 ⚠️
  05-12 █░░░░░░░░░░░░░░░   0问题 ✅
  05-13 █████░░░░░░░░░░░   4问题 修1 ❌1 ❌
  05-14 █░░░░░░░░░░░░░░░   0问题 ✅
  05-15 ███░░░░░░░░░░░░░   2问题 修2 ⚠️
  05-16 ██░░░░░░░░░░░░░░   1问题 ✅
  05-17 █░░░░░░░░░░░░░░░   0问题 ✅
  05-18 █░░░░░░░░░░░░░░░   0问题 ✅

文件数趋势:
  05-12 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░ 38
  05-13 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░ 39
  05-14 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░ 39
  05-15 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░ 41
  05-16 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░ 41
  05-17 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░ 42
  05-18 ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░ 42

日均问题数: 1.8
健康天数: 6/14

Commands

Command Description
gate run Full scan + auto-fix + commit + audit
gate run --quick Pre-commit check (staged files only)
gate run --fixme Auto-fix staged files
gate check <file...> Quick check specific files (no git needed)
gate audit Agent behavior audit only
gate trend [N] Show last N days of quality trends
gate install Install pre-commit hooks & cron
gate version Show version

Rules

Built-in Rules (8 total)

Code Quality (ported from ruff):

Rule Code Severity Auto-fix
syntax_check SYNTAX BLOCKER ❌
ruff_blocker F821, E999 BLOCKER ❌
ruff_fixable F401, F841, E711, E712 FIXABLE ✅
bare_except E722 FIXABLE ✅
hardcoded_paths HARDCODE FIXABLE ✅

AI-Specific:

Rule Code Severity Auto-fix
unsafe_api UNSAFE_* BLOCKER ❌
secret_leak LEAK_SECRET BLOCKER ❌
ai_hallucination AI_* INFO ❌

Write Custom Rules

Create a new .py file in qg/rules/:

from qg.models import Issue, Severity
from qg.rules.base import Rule, register_rule

@register_rule
class MyCustomRule(Rule):
    name = "my_custom_rule"
    severity = Severity.FIXABLE
    description = "Detects something specific"

    def should_check(self, filepath: str) -> bool:
        return filepath.endswith(".py")

    def diagnose(self, filepath: str) -> list[Issue]:
        issues = []
        # Your detection logic...
        return issues

    def fix(self, filepath: str, issue: Issue) -> bool:
        # Your fix logic...
        return True

Rules support two modes:

  • Rule — per-file scanning (for AST analysis, regex)
  • BatchRule — directory-level scanning (for ruff, 10-50x faster)

Configuration

scan_dirs:
  - "~/my-project/src"
  - "~/my-project/scripts"

ignore_patterns:
  - "*__pycache__*"
  - "*/tests/*"

severity:
  blocker_codes: ["F821", "E999", "SYNTAX"]
  auto_fix_codes: ["F401", "F841", "E711", "E712", "E722", "HARDCODE"]

report:
  to_wechat: true

Architecture

gate.py (CLI entry)
└── qg/
    ├── scanner.py      # File discovery
    ├── engine.py       # Diagnostic engine (rule dispatching)
    ├── fixer.py        # Auto-fix engine
    ├── verifier.py     # Post-fix verification
    ├── committer.py    # Git commit automation
    ├── reporter.py     # Report generation (console + log)
    ├── auditor.py      # Agent behavior audit
    ├── dashboard.py    # Trend tracking (SQLite)
    ├── models.py       # Data models
    ├── config.py       # Configuration loader
    └── rules/          # Plugin rules (hot-pluggable)
        ├── base.py     # Rule + BatchRule base classes
        ├── syntax_check.py
        ├── ruff_blocker.py     (BatchRule)
        ├── ruff_fixable.py     (BatchRule)
        ├── bare_except.py
        ├── hardcoded_paths.py
        ├── unsafe_api.py
        ├── secret_leak.py
        └── ai_hallucination.py

Roadmap

  • Phase 1: Python rewrite + plugin architecture
  • Phase 2: AI-specific rules + agent audit + trend dashboard
  • Phase 3: Open-source release + CI integration
  • Phase 4: Security rules (OWASP Top 10 for AI code)
  • Phase 5: GitHub Actions native action
  • Phase 6: VS Code extension

License

MIT License — see LICENSE


Built for the age of AI-generated code.
Because code quality doesn't matter less when AI writes it — it matters more.

Metadata

Release files for agentguard-tool 6.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentguard-tool 6.0.1
File Size Uploaded Provenance Actions
agentguard_tool-6.0.1.tar.gz 49.3 kB With provenance Details for agentguard_tool-6.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentguard-tool 6.0.1
File Interpreter ABI Platform Actions
agentguard_tool-6.0.1-py3-none-any.whl Python 3 none any Details for agentguard_tool-6.0.1-py3-none-any.whl

Total release size: 113.9 kB

Release files / agentguard_tool-6.0.1.tar.gz

Download URL agentguard_tool-6.0.1.tar.gz
Size 49.3 kB
Tags Source
SHA-256 checksum
How to use checksums
92632900546082c43c445449be822bc5f5bb60696ccdc67d03e1a051bc5b0fc4
BLAKE2b-256 checksum
How to use checksums
64ad18f3050f2a5c921194c2f2d32f42af3e17ca8264711b40a5e2785aa5fe16
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / agentguard_tool-6.0.1-py3-none-any.whl

Download URL agentguard_tool-6.0.1-py3-none-any.whl
Size 64.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d3e2a3f5fcb69549ea32d21f8ffed00cd6c11fdc6e2ab5a4eee0ed8b6c977592
BLAKE2b-256 checksum
How to use checksums
48942b1b59c2698d2db530f8ee98af568dac9f9022ce6477dca020da538c9db8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Security for agentguard-tool 6.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for agentguard_tool-6.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page