1.8.12

AI Intervention Agent

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

English | 简体中文

Ever had your AI agent confidently walk off in the wrong direction mid-task? 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 — all 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.

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

pip install ai-intervention-agent

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

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"]`
3. Append the project's recommended prompt rules
   (the "Prompt snippet (copy/paste)" block in this README)
   to my agent rules / system prompt, so the agent always asks me
   through `interactive_feedback` instead of ending tasks silently.
4. Verify by listing MCP servers and confirming `ai-intervention-agent` is loaded.

[!NOTE] interactive_feedback is a long-running tool; some clients enforce a hard request timeout. The Web UI ships a countdown + auto re-submit (feedback.frontend_countdown, default 240s, range 0 or [10, 3600]) to keep sessions alive — the default stays under the common 300s hard timeout.

Screenshots

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

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)
• Agent-loop ergonomics — 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; 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; immune to the Starlette 1.0 breaking change that broke several MCP feedback servers in early 2026

Architecture overview

AIIA runs as a single Python process bridging three surfaces: an MCP stdio server exposing interactive_feedback, a Flask web server with an SSE event bus, 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: Open VSX, VS Code Marketplace, or download the VSIX from GitHub Releases
• 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, macOS native notifications (on by default, toggle in the sidebar's Notification Settings panel) — full settings list and the AppleScript executor security model 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:

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      # default 127.0.0.1
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 (dumps the effective merged config as jq-friendly JSON, with secret-like fields redacted — 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 — step-by-step guide 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 marketplace listing: packages/vscode/CHANGELOG.md
• Contributing: CONTRIBUTING.md · CODE_OF_CONDUCT.md · scripts index: scripts/README.md · i18n guide: docs/i18n.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

Where AIIA sits on the spectrum: AIIA targets the operationally deep end — Web UI + VS Code extension sharing one backend, production-grade observability (/metrics Prometheus endpoint + a reference Grafana dashboard), bilingual i18n + docs, strict invariant test discipline (8,200+ tests + 1,050+ subtests across 40 audit cycles), and a 5-job release pipeline. Want the smallest drop-in? poliva's fork. A desktop app? mcp-feedback-enhanced. Voice / multi-tab UI? Relay or the Node.js fork. Full-stack operational integration? AIIA.

Feature gap callouts (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-06); check each upstream for current numbers. Submit a PR if you'd like another related project listed.

Acknowledgements

This project's heritage traces back to Fábio Ferreira (2024) and Pau Oliva (2025), whose original noopstudios/interactive-feedback-mcp and poliva/interactive-feedback-mcp seeded the MCP interactive_feedback tool surface. Their copyright notices are preserved in LICENSE per the MIT license terms. 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 (PyPI / Open VSX / VS Code Marketplace publisher).

License

MIT License