{
  "markdown": "# 🔍 Agent Polis\n\n**Impact Preview for AI Agents - \"Terraform plan\" for autonomous AI actions**\n\n<!-- mcp-name: io.github.agent-polis/impact-preview -->\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n\n> See exactly what will change before any AI agent action executes.\n\nAgent 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.\n\n## 🎯 The Problem\n\nAutonomous AI agents are powerful but dangerous. Recent incidents:\n\n- **Replit Agent** deleted a production database, then lied about it\n- **Cursor YOLO mode** deleted an entire system including itself\n- **Claude Code** learned to bypass safety restrictions via shell scripts\n\nDevelopers 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.\n\n## 🚀 The Solution\n\n```\nAI Agent proposes action → Agent Polis analyzes impact → Human reviews diff → Approve/Reject → Execute\n```\n\n```diff\n# Example: Agent wants to write to config.yaml\n- database_url: postgresql://localhost:5432/dev\n+ database_url: postgresql://prod-server:5432/production\n! WARNING: Production database URL detected (CRITICAL RISK)\n```\n\n## ✨ Features\n\n- **Impact Preview**: See file diffs, risk assessment, and warnings before execution\n- **Approval Workflow**: Approve, reject, or modify proposed actions\n- **Risk Assessment**: Automatic detection of high-risk operations (production data, system files, etc.)\n- **Audit Trail**: Event-sourced log of every proposed and executed action\n- **SDK Integration**: Easy `@require_approval` decorator for your agent code\n- **Dashboard**: Streamlit UI for reviewing and approving actions\n\n## 🚀 Quick Start (2 minutes)\n\nThe fastest way to try Agent Polis is the **MCP server** with Claude Desktop or Cursor.\n\n### 1. Install & Run\n\n```bash\npip install impact-preview\nimpact-preview-mcp\n```\n\n### 2. Configure Claude Desktop\n\nAdd to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n    \"mcpServers\": {\n        \"impact-preview\": {\n            \"url\": \"http://localhost:8000/mcp\"\n        }\n    }\n}\n```\n\n### 3. Try It\n\nAsk Claude to edit a file - it now has these tools:\n\n| Tool | What it does |\n|------|--------------|\n| `preview_file_write` | Shows diff before any edit |\n| `preview_file_delete` | Shows what will be lost |\n| `preview_shell_command` | Flags dangerous commands |\n| `check_path_risk` | Quick risk check for any path |\n\n**Example prompt:**\n> \"Preview what would happen if you changed the database URL in config.yaml to point to production\"\n\nClaude will show you the diff and risk assessment *before* making changes.\n\n---\n\n## 📦 Full Server Installation\n\nFor the complete approval workflow with dashboard and API:\n\n```bash\n# Using Docker (recommended)\ndocker-compose up -d\n\n# Or locally\npip install impact-preview\nimpact-preview\n```\n\n### Register an Agent\n\n```bash\ncurl -X POST http://localhost:8000/api/v1/agents/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"my-agent\", \"description\": \"My AI coding assistant\"}'\n```\n\n### Submit Action → Review → Approve\n\n```bash\n# Submit\ncurl -X POST http://localhost:8000/api/v1/actions \\\n  -H \"X-API-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"action_type\": \"file_write\", \"target\": \"/app/config.yaml\", \"description\": \"Update DB URL\", \"payload\": {\"content\": \"db: prod\"}}'\n\n# Preview\ncurl http://localhost:8000/api/v1/actions/ACTION_ID/preview -H \"X-API-Key: YOUR_API_KEY\"\n\n# Approve (or reject)\ncurl -X POST http://localhost:8000/api/v1/actions/ACTION_ID/approve -H \"X-API-Key: YOUR_API_KEY\"\n```\n\n### Audit Trail (Events)\n\nYou can retrieve the complete audit trail for an action:\n\n```bash\ncurl http://localhost:8000/api/v1/actions/ACTION_ID/events -H \"X-API-Key: YOUR_API_KEY\"\n```\n\n`ActionPreviewGenerated` event payload includes machine-readable governance context:\n- `data.governance.policy.decision` / `data.governance.policy.matched_rule_id`\n- `data.governance.scanner.reason_ids` / `data.governance.scanner.max_severity`\n\n---\n\n## 🐍 SDK Integration\n\nWrap your agent's dangerous operations:\n\n```python\nfrom agent_polis import AgentPolisClient\n\nclient = AgentPolisClient(api_url=\"http://localhost:8000\", api_key=\"YOUR_KEY\")\n\n# Decorator approach - blocks until human approves\n@client.require_approval(action_type=\"file_write\")\ndef write_config(path: str, content: str):\n    with open(path, 'w') as f:\n        f.write(content)\n\n# This will: submit → wait for approval → execute only if approved\nwrite_config(\"/etc/myapp/config.yaml\", \"new content\")\n```\n\n## 🖥️ Dashboard\n\nLaunch the Streamlit dashboard to review pending actions:\n\n```bash\npip install impact-preview[ui]\nstreamlit run src/agent_polis/ui/app.py\n```\n\n## 📚 API Reference\n\n### Actions API\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/v1/actions` | POST | Submit action for approval |\n| `/api/v1/actions` | GET | List your actions |\n| `/api/v1/actions/pending` | GET | List pending approvals |\n| `/api/v1/actions/{id}` | GET | Get action details |\n| `/api/v1/actions/{id}/preview` | GET | Get impact preview |\n| `/api/v1/actions/{id}/diff` | GET | Get diff output |\n| `/api/v1/actions/{id}/approve` | POST | Approve action |\n| `/api/v1/actions/{id}/reject` | POST | Reject action |\n| `/api/v1/actions/{id}/execute` | POST | Execute approved action |\n\n### Action Types\n\n- `file_write` - Write content to a file\n- `file_create` - Create a new file\n- `file_delete` - Delete a file\n- `file_move` - Move/rename a file\n- `db_query` - Execute a database query (read)\n- `db_execute` - Execute a database statement (write)\n- `api_call` - Make an HTTP request\n- `shell_command` - Run a shell command\n- `custom` - Custom action type\n\n### Risk Levels\n\n- **Low**: Read operations, safe changes\n- **Medium**: Write operations to non-critical files\n- **High**: Delete operations, system files\n- **Critical**: Production data, irreversible changes\n\n## 🔧 Configuration\n\n```bash\n# .env\nSECRET_KEY=your-secret-key\nDATABASE_URL=postgresql+asyncpg://user:pass@host:5432/agent_polis\nREDIS_URL=redis://localhost:6379/0\n\n# Optional\nFREE_TIER_ACTIONS_PER_MONTH=100\nLOG_LEVEL=INFO\n```\n\n## 🗺️ Roadmap\n\n| Version | Focus | Status |\n|---------|-------|--------|\n| v0.2.0 | File operation preview | Current |\n| v0.3.0 | Database operation preview | Planned |\n| v0.4.0 | API call preview | Planned |\n| v0.5.0 | IDE integrations (Cursor, VS Code) | Planned |\n| v1.0.0 | Production ready | Planned |\n\n## 🤝 Contributing\n\n```bash\ngit clone https://github.com/agent-polis/impact-preview.git\ncd impact-preview\npip install -e .[dev]\npre-commit install\npytest\n```\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\nBuilt for developers who want AI agents they can actually trust.\n",
  "bytes": 7138,
  "sha": "a9be48038f27b5e235de0aa91539d32a5ccc0d125f9d2e0d4b11dbde68f86dab",
  "repo_slug": "agent-polis/impact-preview",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_agent_polis_impact_preview_30d60405/readme"
}