Guardian

Guardian is an open-source middleware and SDK for AI coding assistants. It acts as a developer-controlled approval layer that intercepts operations proposed by AI agents on your machine, evaluates them against local rules, groups repetitive operations, and remembers approved patterns to eliminate approval fatigue without sacrificing control.

Why Guardian Exists

AI coding assistants are highly capable but require access to execute shell commands, install dependencies, read sensitive files, and modify repositories. Managing these permissions manually is a trade-off:

• Unrestricted execution presents high risk to repository integrity and secret leakage.
• Manual approval for every action causes severe cognitive overload and prompt fatigue.

Guardian solves this by acting as a lightweight, deterministic approval engine between your machine and the assistant.

Key Features

• Deterministic Rule Pack: Out-of-the-box rules evaluating actions into Auto Allow, Ask, or Block.
• Action Grouping: Intelligently groups repetitive actions (such as multiple file reads/writes, formatter runs, or test execution loops) into a single approval prompt.
• Approval Memory: Automatically remembers safe interaction patterns and trust configurations to prevent repeated prompting.
• Session Auditing: Logs all evaluated actions and decisions to a local SQLite timeline database.
• Extensible Integration: Supports major command-line and editor-based AI coding assistants through native adapters.

Supported AI Coding Assistants

Guardian is designed to work with a variety of tools. Built-in translation adapters support:

• Aider
• Claude Code
• Cline
• Codex
• Cursor
• Gemini CLI
• Roo Code

Installation

Guardian requires Python 3.11 or higher.

Install Guardian using pip:

pip install guardian-ai-monitor

For more details on requirements and platform support, see the Installation Guide.

Quick Start

Get started with Guardian in under two minutes:

1. Initialize configuration in your project root:

   guardian init
   

   This creates a default guardian.toml file.

2. Verify your environment:

   guardian doctor
   

   This checks for configuration file validity, SQLite database connectivity, and environment variables.

For a full walkthrough, refer to the Quickstart Guide.

Core Concepts

Understanding how Guardian models action lifecycles:

graph TD
    A[AI Assistant Request] --> B[Action Intercepted]
    B --> C[Preview Generated]
    C --> D[Risk Assessment / Review]
    D --> E{Rule & Memory Evaluation}
    E -->|Safe / Trusted| F[Auto Allow]
    E -->|Moderate Risk| G[Ask Developer]
    E -->|High Risk / Blocked| H[Block/Deny]
    F --> I[Final Outcome Recorded]
    G -->|Approved| I
    G -->|Rejected| H

• Action: The raw command, file read/write, or network call proposed by the assistant.
• Preview: A structured preview showing the files, directories, or execution scopes affected.
• Review: An evaluation report containing risk scores, reasons, and classification categories.
• Decision: The final policy outcome (allow, ask, or deny) generated by the engine.
• Outcome: The recorded lifecycle status tracking whether the operation succeeded or was rejected.

Documentation Links

• Installation Guide - System requirements, installation methods, and troubleshooting.
• Quickstart Guide - Five-minute walk-through of core commands.
• Configuration Reference - Details on custom guardian.toml options and defaults.
• CLI Reference - Syntax, arguments, and examples for all CLI commands.
• Rule Pack Guide - In-depth look at Auto Allow, Ask, Block, Grouping, and Approval Memory rules.

Contributing

We welcome contributions! Please see our Contributing Guidelines for local setup, testing instructions, and style guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.