🔍 Agent Polis

Impact Preview for AI Agents - "Terraform plan" for autonomous AI actions

See exactly what will change before any AI agent action executes.

Agent Polis intercepts proposed actions from autonomous AI agents, analyzes their impact, shows you a diff preview of what will change, and only executes after human approval. Stop worrying about your AI agent deleting your production database.

🎯 The Problem

Autonomous AI agents are powerful but dangerous. Recent incidents:

• Replit Agent deleted a production database, then lied about it
• Cursor YOLO mode deleted an entire system including itself
• Claude Code learned to bypass safety restrictions via shell scripts

Developers want to use AI agents but don't trust them. Current solutions show what agents want to do, not what will happen. There's no "terraform plan" equivalent for AI agent actions.

🚀 The Solution

AI Agent proposes action → Agent Polis analyzes impact → Human reviews diff → Approve/Reject → Execute

# Example: Agent wants to write to config.yaml
- database_url: postgresql://localhost:5432/dev
+ database_url: postgresql://prod-server:5432/production
! WARNING: Production database URL detected (CRITICAL RISK)

✨ Features

• Impact Preview: See file diffs, risk assessment, and warnings before execution
• Approval Workflow: Approve, reject, or modify proposed actions
• Risk Assessment: Automatic detection of high-risk operations (production data, system files, etc.)
• Audit Trail: Event-sourced log of every proposed and executed action
• SDK Integration: Easy @require_approval decorator for your agent code
• Dashboard: Streamlit UI for reviewing and approving actions

🚀 Quick Start (2 minutes)

The fastest way to try Agent Polis is the MCP server with Claude Desktop or Cursor.

1. Install & Run

pip install impact-preview
impact-preview-mcp

2. Configure Claude Desktop

Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
    "mcpServers": {
        "impact-preview": {
            "url": "http://localhost:8000/mcp"
        }
    }
}

3. Try It

Ask Claude to edit a file - it now has these tools:

Example prompt:

"Preview what would happen if you changed the database URL in config.yaml to point to production"

Claude will show you the diff and risk assessment before making changes.

📦 Full Server Installation

For the complete approval workflow with dashboard and API:

# Using Docker (recommended)
docker-compose up -d

# Or locally
pip install impact-preview
impact-preview

Register an Agent

curl -X POST http://localhost:8000/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "description": "My AI coding assistant"}'

Submit Action → Review → Approve

# Submit
curl -X POST http://localhost:8000/api/v1/actions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action_type": "file_write", "target": "/app/config.yaml", "description": "Update DB URL", "payload": {"content": "db: prod"}}'

# Preview
curl http://localhost:8000/api/v1/actions/ACTION_ID/preview -H "X-API-Key: YOUR_API_KEY"

# Approve (or reject)
curl -X POST http://localhost:8000/api/v1/actions/ACTION_ID/approve -H "X-API-Key: YOUR_API_KEY"

Audit Trail (Events)

You

... View full README on GitHub