AI Intervention Agent▌

When using AI CLIs/IDEs, agents can drift from your intent. This project gives you a simple way to **intervene** at key moments, review context in a Web UI, and send your latest instructions via `interactive_feedback` so the agent can continue on track. Works with `Cursor`, `VS Code`, `Claude Code`, `Augment`, `Windsurf`, `Trae`, and more. ## Quick start 1. Install: ```bash pip install ai-intervention-agent # or uv add ai-intervention-agent ``` 2. Configure your AI tool to launch the MCP server via `uvx`: ```json { "mcpServers": { "ai-intervention-agent": { "command": "uvx", "args": ["ai-intervention-agent"], "timeout": 600, "autoApprove": ["interactive_feedback"] } } } ``` > [!NOTE] > `interactive_feedback` is a **long-running tool**. Some clients have a hard request timeout, so the Web UI provides a countdown + auto re-submit option to keep sessions alive.

Prompt snippet (copy/paste)

```text - Only ask me through the MCP `ai-intervention-agent` tool; do not ask directly in chat or ask for end-of-task confirmation in chat. - If a tool call fails, keep asking again through `ai-intervention-agent` instead of making assumptions, until the tool call succeeds. ai-intervention-agent usage details: - If requirements are unclear, use `ai-intervention-agent` to ask for clarification with predefined options. - If there are multiple approaches, use `ai-intervention-agent` to ask instead of deciding unilaterally. - If a plan/strategy needs to change, use `ai-intervention-agent` to ask instead of deciding unilaterally. - Before finishing a request, always ask for feedback via `ai-intervention-agent`. - Do not end the conversation/request unless the user explicitly allows it via `ai-intervention-agent`. ```

## Screenshots

_{Feedback page (auto switches between dark/light)}

More screenshots (empty state + settings)

_{Empty state (auto switches between dark/light)}

_{Settings (dark)}

## Key features - **Real-time intervention**: the agent pauses and waits for your input via `interactive_feedback` - **Web UI**: Markdown, code highlighting, and math rendering - **Multi-task**: tab switching with independent countdown timers - **Auto re-submit**: keep sessions alive by auto-submitting at timeout - **Notifications**: web / sound / system / Bark - **SSH-friendly**: great with port forwarding ## VS Code extension (optional) | Item | Value | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Purpose | Embed the interaction panel into VS Code’s sidebar to avoid switching to a browser. | | Install (Open VSX) | [Open VSX](https://open-vsx.org/extension/xiadengma/ai-intervention-agent) | | Download VSIX (GitHub Release) | [GitHub Releases](https://github.com/xiadengma/ai-intervention-agent/releases/latest) | | Setting | `ai-intervention-agent.serverUrl` (should match your Web UI URL, e.g. `http://localhost:8080`; you can change `web_ui.port` in [`config.jsonc.default`](config.jsonc.default)) | ## Configuration | Item | Value | | ---------------- | ------------------------------------------------------------------------------------------------- | | Docs (English) | [docs/configuration.md](docs/configuration.md) | | Docs (简体中文) | [docs/configuration.zh-CN.md](docs/configuration.zh-CN.md) | | Default template | [`config.jsonc.default`](config.jsonc.default) (on first run it will be copied to `config.jsonc`) | | OS | User config directory | | ------- | ------------------------------------------------------ | | Linux | `~/.config/ai-intervention-agent/` | | macOS | `~/Library/Application Support/ai-intervention-agent/` | | Windows | `%APPDATA%/ai-intervention-agent/` | ## Architecture ```mermaid flowchart TD subgraph CLIENTS["AI clients"] AI_CLIENT["AI CLI / IDE
(Cursor, VS Code, Claude Code, ...)"] end subgraph MCP_PROC["MCP server process"] MCP_SRV["ai-intervention-agent
(server.py)"] MCP_TOOL["MCP tool
interactive_feedback"] CFG_MGR["Config manager
(config_manager.py)"] NOTIF_MGR["Notification manager
(notification_manager.py)"] end subgraph WEB_PROC["Web UI process"] WEB_SRV["Web UI service
(web_ui.py / Flask)"] HTTP_API["HTTP API
(/api/*)"] TASK_Q["Task queue
(task_queue.py)"] WEB_SRV --> HTTP_API WEB_SRV --> TASK_Q end subgraph USER_UI["User interfaces"] BROWSER["Browser"] VSCODE["VS Code extension
(Webview)"] end CFG_FILE["config.jsonc
(user config directory)"] AI_CLIENT -->|MCP call| MCP_TOOL MCP_SRV -->|exposes| MCP_TOOL MCP_TOOL -->|ensure Web UI running| WEB_SRV MCP_TOOL <-->|create task / poll result| HTTP_API BROWSER <-->|HTTP| HTTP_API VSCODE <-->|HTTP| HTTP_API CFG_MGR <-->|read/write| CFG_FILE WEB_SRV <-->|read| CFG_FILE MCP_SRV --> NOTIF_MGR NOTIF_MGR -->|web / sound / system / Bark| USER["User"] ``` ## Documentation - **API docs index**: [`docs/api/index.md`](docs/api/index.md) - **API docs (简体中文)**: [`docs/api.zh-CN/index.md`](docs/api.zh-CN/index.md) - **DeepWiki**: [deepwiki.com/xiadengma/ai-intervention-agent](https://deepwiki.com/xiadengma/ai-intervention-agent) ## Related projects - [interactive-feedback-mcp](https://github.com/poliva/interactive-feedback-mcp) - [mcp-feedback-enhanced](https://github.com/Minidoracat/mcp-feedback-enhanced) - [cunzhi](https://github.com/imhuso/cunzhi) - [other interactive-feedback-mcp](https://github.com/Pursue-LLL/interactive-feedback-mcp) ## License MIT License