agentguard-tool

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

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

---

🚀 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)

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:

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

---

Rules

Built-in Rules (8 total)

Code Quality (ported from ruff):

AI-Specific:

---

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.}