`approval-gate`

A local-first MCP server and CLI that forces AI agents to pause risky actions for human approval with durable state and audit logs.

License Language Status Python License: MIT MCP

🎯 Why?

Trending repos show agents getting more autonomous, but guardrails are mostly blockers or prompt-level policies. Destructive Command Guard blocks commands, while agent frameworks and channel SDKs still lack a tiny durable human-in-the-loop approval queue that any MCP client or CLI agent can use. approval-gate fills that gap with a single-file SQLite-backed approval gateway, risk scoring, and audit trail.

Target audience: Developers running coding agents, DevOps agents, or MCP-powered assistants who want safe autonomy with explicit human sign-off for risky commands.

✨ Features

✨ MCP stdio server with request_approval, list_approvals, resolve_approval, and audit_tail tools
✨ CLI for creating, listing, approving, denying, and auditing approval requests
✨ Rule-based risk scoring for shell commands with optional auto-approval for low-risk actions

🚀 Quick Start

# Install
pip install approval-gate

# Run
approval-gate --help

📦 Installation

From Source

git clone https://github.com/YOUR_USERNAME/approval-gate.git
cd approval-gate

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest -v

🎬 Demo

The GIF above was recorded using Charm VHS:

vhs < demo.tape

📖 Usage

# Show help
approval-gate --help

# Common usage examples
approval-gate --example

🏗️ Architecture

graph LR
    A[Input] --> B[Core Engine]
    B --> C[Output]
    B --> D[Plugins]
    D --> E[Extensions]

🤝 Contributing

Contributions are welcome! Please:

Fork the repo
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

If this project helped you, please ⭐ star it!

Made with ❤️ and AI