agentguard-tool 1.0.5

AI-native quality gate for agent-generated code — scan, audit, auto-fix, trend

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 (3 rules)

Rule	Severity	What It Finds
unsafe_api	🚫 BLOCKER	eval(), exec(), os.system(), subprocess(shell=True), pickle.loads()
secret_leak	🚫 BLOCKER	Hardcoded API keys, tokens, passwords in source code
ai_hallucination	ℹ️ INFO	AI placeholder comments, suspicious module names, giant auto-generated functions

📊 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

---

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