<div align="center">

# `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](https://img.shields.io/badge/license-MIT-blue.svg) ![Language](https://img.shields.io/badge/language-python-green.svg) ![Status](https://img.shields.io/badge/status-active-success.svg) [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![MCP](https://img.shields.io/badge/MCP-server-8A2BE2.svg)](https://modelcontextprotocol.io/)

<img src="demo.gif" alt="Demo" width="700" />

</div>

---

## 🎯 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

```bash
# Install
pip install approval-gate

# Run
approval-gate --help
```

## 📦 Installation

### From Source

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

```bash
# 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](https://github.com/charmbracelet/vhs):

```bash
vhs < demo.tape
```

## 📖 Usage

```bash
# Show help
approval-gate --help

# Common usage examples
approval-gate --example
```

## 🏗️ Architecture

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

## 🤝 Contributing

Contributions are welcome! Please:

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

## 📄 License

MIT © 2026 — See [LICENSE](LICENSE) for details.

---

<div align="center">

**If this project helped you, please ⭐ star it!**

[Made with ❤️ and AI](https://github.com)

</div>