🔍 Agent Polis

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

<!- - mcp-name: io.github.agent-polis/impact-preview - ->

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:

| Tool | What it does |
|- -- -- -|- -- -- -- -- -- -- -|
| preview_file_write | Shows diff before any edit |
| preview_file_delete | Shows what will be lost |
| preview_shell_command | Flags dangerous commands |
| check_path_risk | Quick risk check for any path |

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 can retrieve the complete audit trail for an action:

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

ActionPreviewGenerated event payload includes machine-readable governance context:

• data.governance.policy.decision / data.governance.policy.matched_rule_id
• data.governance.scanner.reason_ids / data.governance.scanner.max_severity

# 🐍 SDK Integration

Wrap your agent's dangerous operations:

from agent_polis import AgentPolisClient

client = AgentPolisClient(api_url="http://localhost:8000", api_key="YOUR_KEY")

#  Decorator approach - blocks until human approves
@client.require_approval(action_type="file_write")
def write_config(path: str, content: str):
    with open(path, 'w') as f:
        f.write(content)

#  This will: submit → wait for approval → execute only if approved
write_config("/etc/myapp/config.yaml", "new content")

# 🖥️ Dashboard

Launch the Streamlit dashboard to review pending actions:

pip install impact-preview[ui]
streamlit run src/agent_polis/ui/app.py

# 📚 API Reference

# # Actions API

| Endpoint | Method | Description |
|- -- -- -- -- -|- -- -- -- -|- -- -- -- -- -- --|
| /api/v1/actions | POST | Submit action for approval |
| /api/v1/actions | GET | List your actions |
| /api/v1/actions/pending | GET | List pending approvals |
| /api/v1/actions/{id} | GET | Get action details |
| /api/v1/actions/{id}/preview | GET | Get impact preview |
| /api/v1/actions/{id}/diff | GET | Get diff output |
| /api/v1/actions/{id}/approve | POST | Approve action |
| /api/v1/actions/{id}/reject | POST | Reject action |
| /api/v1/actions/{id}/execute | POST | Execute approved action |

# # Action Types

• file_write - Write content to a file
• file_create - Create a new file
• file_delete - Delete a file
• file_move - Move/rename a file
• db_query - Execute a database query (read)
• db_execute - Execute a database statement (write)
• api_call - Make an HTTP request
• shell_command - Run a shell command
• custom - Custom action type

# # Risk Levels

• Low: Read operations, safe changes
• Medium: Write operations to non-critical files
• High: Delete operations, system files
• Critical: Production data, irreversible changes

# 🔧 Configuration

#  .env
SECRET_KEY=your-secret-key
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/agent_polis
REDIS_URL=redis://localhost:6379/0

#  Optional
FREE_TIER_ACTIONS_PER_MONTH=100
LOG_LEVEL=INFO

# 🗺️ Roadmap

| Version | Focus | Status |
|- -- -- -- --|- -- -- --|- -- -- -- -|
| v0.2.0 | File operation preview | Current |
| v0.3.0 | Database operation preview | Planned |
| v0.4.0 | API call preview | Planned |
| v0.5.0 | IDE integrations (Cursor, VS Code) | Planned |
| v1.0.0 | Production ready | Planned |

# 🤝 Contributing

git clone https://github.com/agent-polis/impact-preview.git
cd impact-preview
pip install -e .[dev]
pre-commit install
pytest

# 📄 License

MIT License - see LICENSE for details.

Built for developers who want AI agents they can actually trust.