AI Intervention Agent

Real-time user intervention for MCP agents: pause, course-correct, resume.

 

Quick start · Screenshots · Key features · VS Code extension · Configuration · Documentation

---

AI Intervention Agent gives you a Web UI to pause the agent at key moments, review what it's about to do, type a course-correction, attach screenshots, and resume it. Everything goes through the MCP interactive_feedback tool, without ending the conversation.

Works with Cursor, VS Code, Claude Code, Augment, Windsurf, Trae, and more.

Quick start

Point your AI tool at the MCP server via uvx (installs and runs the latest version automatically):

{
  "mcpServers": {
    "ai-intervention-agent": {
      "command": "uvx",
      "args": ["ai-intervention-agent"],
      "timeout": 600,
      "autoApprove": ["interactive_feedback"]
    }
  }
}

Then add the prompt snippet below to your agent rules / system prompt, so the agent asks you through interactive_feedback instead of finishing tasks silently.

Prompt snippet (copy/paste)

- 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`.

Alternative: install with pip

Install the package (needs Python 3.11 or newer; remember to pip install --upgrade ai-intervention-agent periodically):

pip install ai-intervention-agent

Then configure your AI tool to launch the installed entry point:

{
  "mcpServers": {
    "ai-intervention-agent": {
      "command": "ai-intervention-agent",
      "args": [],
      "timeout": 600,
      "autoApprove": ["interactive_feedback"]
    }
  }
}

Alternative: let your AI set it up for you

If your IDE/CLI has an AI agent (Cursor, Claude Code, VS Code, Windsurf, Trae, Augment, ...), paste this prompt in chat and let it write the config:

Please configure my IDE / AI tool to use the `ai-intervention-agent` MCP server:

1. Locate the correct MCP config file for my current IDE
   (e.g. `.cursor/mcp.json` or `~/.cursor/mcp.json` for Cursor,
    `~/.claude.json` for Claude Code,
    `.vscode/mcp.json` for VS Code).
2. Add this entry under `mcpServers`:
   - command: `uvx`
   - args: `["ai-intervention-agent"]`
   - timeout: 600
   - autoApprove: `["interactive_feedback"]`
   Keep every other server and setting in the file exactly as it is.
   If an `ai-intervention-agent` entry already exists, show me the
   difference and ask before replacing it.
3. Open the link below and append the rules from its
   "Prompt snippet (copy/paste)" block to my agent rules / system prompt,
   so the agent always asks me through `interactive_feedback`
   instead of ending tasks silently:
   https://raw.githubusercontent.com/xiadengma/ai-intervention-agent/main/README.md
   If you cannot open that link, ask me to paste the block.
4. Verify by listing MCP servers and confirming `ai-intervention-agent` is loaded
   (tell me if I need to restart or reload the tool).
5. Finish by telling me which files you changed and what the check showed.

Note

interactive_feedback is a long-running tool, and some clients enforce a hard request timeout. To keep sessions alive, the Web UI ships a countdown with auto re-submit (feedback.frontend_countdown, default 240 seconds, range 0 or [10, 3600]). The default stays under the common 300-second hard timeout.

Screenshots

_{Feedback page · auto switches between dark/light · multi-task tabs with independent countdowns}

More screenshots (empty state + settings)

_{Empty state · waiting for the next interactive request}

_{Settings · notifications · Bark · sound · feedback countdown · auto switches between dark/light}

Key features

• Real-time intervention: the agent pauses and waits for your input via interactive_feedback
• Web UI: Markdown, code highlighting, and math rendering out of the box
• Multi-task tabs: concurrent requests with independent countdowns, per-task draft autosave, and auto re-submit that keeps long sessions alive (your typed text and checked options are submitted at zero, never an empty prompt)
• Typing-hold: the countdown auto-extends while you type and never fires mid-input (web page and VS Code extension alike)
• Skill and command picker: type / in the feedback box to insert an installed Agent Skill or custom command (Cursor / Claude Code / Codex layouts, auto-detected or set with [feedback] skill_dirs)
• Local images in prompts: write ![alt](path/to/image.png) in the message and the Web UI shows the file; only images inside your workspace folders and the temp directory are read (adjust with [feedback] local_image_dirs); click any image in the message to see it larger (Web UI and VS Code panel)
• Agent-loop context: per-task header_label context chips, feedback_placeholder hints, and loop engineering metadata (loop_id, loop_phase, success_criteria)
• Notifications: web / sound / system / Bark (iOS push), plus custom notification sound upload
• SSH / LAN friendly: works behind port forwarding; listens on this computer only by default, and once bind_interface is a LAN address mDNS publishes a <host>.local URL when supported
• i18n: Web UI + VS Code extension shipped in en / zh-CN / zh-TW
• PWA, offline-aware, WCAG 2.1 AA accessible: installable from the browser, with contrast / focus / reduced-motion audited and locked by invariant tests
• Stable install: built on Flask 3.x with conservative dependency pins; not affected by the Starlette 1.0 breaking change that broke several MCP feedback servers in early 2026

Architecture overview

AIIA runs as two cooperating Python processes bridging three surfaces: an MCP stdio server exposing interactive_feedback (one per IDE window), a Flask web server with an SSE event bus (started on demand as a subprocess and shared by every window), and a persistent task queue feeding the notification stack. The component diagram, the interaction and failure-recovery sequence diagrams, the agent-side MCP parameter table, and the runtime invariant catalogue live in docs/architecture.md.

VS Code extension (optional)

Embeds the interaction panel into VS Code's sidebar so you never switch to a browser.

• Install: from Open VSX (the extension registry that Cursor, VSCodium, Windsurf and other VS Code-based editors use), or download the VSIX from GitHub Releases. Microsoft's VS Code does not search Open VSX, so install the VSIX there: Command Palette → Extensions: Install from VSIX...
• Key setting: ai-intervention-agent.serverUrl must match your Web UI URL (e.g. http://localhost:8080; change the port via web_ui.port in config.toml.default)
• More: ai-intervention-agent.logLevel and macOS native notifications (on by default, toggle in the sidebar panel's Settings page). The full settings list and the AppleScript executor security model are in packages/vscode/README.md

Configuration

On first run, config.toml is created from config.toml.default in your OS user config directory (the full TOML reference is in docs/configuration.md):

OS	User config directory
Linux	~/.config/ai-intervention-agent/
macOS	~/Library/Application Support/ai-intervention-agent/
Windows	%APPDATA%/ai-intervention-agent/

For uvx, Docker, systemd, or SSH-remote runtimes where editing the file is awkward, the most-used web_ui settings can be overridden by env var at startup (invalid values log a WARNING and fall back safely; full surface in docs/configuration.md#environment-variable-overrides):

export AI_INTERVENTION_AGENT_WEB_UI_HOST=0.0.0.0      # listen address, default 127.0.0.1 (this computer only); 0.0.0.0 = all interfaces
export AI_INTERVENTION_AGENT_WEB_UI_PORT=8181         # default 8080, range [1, 65535]
export AI_INTERVENTION_AGENT_WEB_UI_LANGUAGE=en       # auto / en / zh-CN / zh-TW
uvx ai-intervention-agent

CLI inspection: --version, --help, and --print-config. The last one dumps the effective merged config as jq-friendly JSON, with secret-like fields redacted, and answers "is my port from env or from config.toml?" in one pipeline.

On iPhone, the smoothest setup wraps the Web UI in a Shortcuts automation and points Bark notification taps at it. The step-by-step guide is in docs/configuration.md#recommended-iphone-setup-shortcuts--bark.

Documentation

• Docs index (by audience): docs/README.md · docs/README.zh-CN.md
• Architecture (diagrams + agent workflow): docs/architecture.md
• MCP tool reference: docs/mcp_tools.md · docs/mcp_tools.zh-CN.md
• API docs: docs/api/index.md · docs/api.zh-CN/index.md
• Troubleshooting / FAQ: docs/troubleshooting.md · docs/troubleshooting.zh-CN.md
• Release notes: CHANGELOG.md · VS Code extension (the Open VSX listing): packages/vscode/CHANGELOG.md
• Contributing: CONTRIBUTING.md · CODE_OF_CONDUCT.md · scripts index: scripts/README.md · i18n guide: docs/i18n.md
• Support & security: SUPPORT.md · SECURITY.md
• Release recovery runbook: docs/release-recovery.md · docs/release-recovery.zh-CN.md
• DeepWiki Q&A (AI-augmented Q&A over the repo):

Related projects

Project	Stars (approx.)	Focus
mcp-feedback-enhanced (Minidoracat)	~3.8k	Largest sibling; Web UI + Tauri desktop app, auto-command execution, SSH Remote / WSL detection.
cunzhi (imhuso)	~1.4k	Chinese-language project focused on preventing premature task completion.
Relay (andeya)	new	Multi-IDE relay, multi-tab session merging, native desktop window, Cursor usage monitoring.
interactive-feedback-mcp (Node.js)	new	Node.js port with WebSocket UI and Speech-to-Text via OpenAI Whisper.
interactive-feedback-mcp (junanchn)	~30	Win32-native always-on-top window, auto-reply rules.
interactive-feedback-mcp (poliva)	~310	Direct ancestor fork (see Acknowledgements); minimal Python MCP, single feedback dialog.
interactive-feedback-mcp (Pursue-LLL)	~30	Independent smaller-scale fork emphasising minimal dependencies.

Where AIIA sits on the spectrum: AIIA targets the operationally deep end. The Web UI and the VS Code extension share one backend, and observability comes from a /api/system/metrics Prometheus endpoint plus a reference Grafana dashboard. The Web UI ships in three languages and the docs in two, the project follows an invariant test discipline (15,500+ tests + 1,300+ subtests across 40 audit cycles), and releases run through a 4-job pipeline. If you want the smallest drop-in, use poliva's fork; for a desktop app, mcp-feedback-enhanced; for voice input or a multi-tab UI, Relay or the Node.js fork.

Feature gaps (contributions welcome): Speech-to-Text input, always-on-top native window, Cursor usage monitoring, multi-tab session merging UI.

Star counts are approximate snapshots (last reviewed 2026-10); check each upstream for current numbers. Submit a PR if you'd like another related project listed.

Acknowledgements

The MCP interactive_feedback tool surface comes from two earlier projects: Fábio Ferreira's original noopstudios/interactive-feedback-mcp (2024) and Pau Oliva's poliva/interactive-feedback-mcp (2025). Their copyright notices are kept in LICENSE, as the MIT license requires. The v1.5.x line is a substantial rewrite (Web UI, VS Code extension, i18n, notification stack, CI/CD pipeline), owned and maintained by @xiadengma, the publisher on PyPI and Open VSX.

License

MIT License