AI Intervention Agent

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

Ever had your AI agent confidently walk off in the wrong direction mid-task? AI Intervention Agent gives you a Web UI topausethe agent at key moments, review what it's about to do, type a course-correction, attach screenshots, andresume— all through the MCPinteractive_feedbacktool, without ending the conversation.

Works withCursor,VS Code,Claude Code,Augment,Windsurf,Trae, and more.

Point your AI tool at the MCP server viauvx(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 throughinteractive_feedbackinstead 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.

Install the package (remember topip install --upgrade ai-intervention-agentperiodically):

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"] } } }

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"] 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_feedbackis along-running tool; some clients enforce a hard request timeout. The Web UI ships a countdown + auto re-submit (feedback.frontend_countdown, default240s, range0or[10, 3600]) to keep sessions alive — the default stays under the common 300s hard timeout.

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

Empty state · waiting for the next interactive request

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

- Real-time intervention— the agent pauses and waits for your input viainteractive_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-taskheader_labelcontext chips,question_type='yesno'one-click decisions, andfeedback_placeholderhints
- Notifications— web / sound / system / Bark (iOS push), plus custom notification sound upload
- SSH / LAN friendly— works behind port forwarding; mDNS publishes a<host>.localURL when supported
- i18n— Web UI + VS Code extension shipped inen/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 theStarlette 1.0 breaking changethat broke several MCP feedback servers in early 2026

AIIA runs as a single Python process bridging three surfaces: an MCP stdio server exposinginteractive_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 indocs/architecture.md.

- Install:Open VSX,VS Code Marketplace, or download the VSIX fromGitHub Releases
- Key setting:ai-intervention-agent.serverUrl— must match your Web UI URL (e.g.http://localhost:8080; change the port viaweb_ui.portinconfig.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 inpackages/vscode/README.md

On first run,config.tomlis created fromconfig.toml.defaultin your OS user config directory — the full TOML reference is indocs/configuration.md:

Foruvx, Docker, systemd, or SSH-remote runtimes where editing the file is awkward, the most-usedweb_uisettings can be overridden by env var at startup (invalid values log aWARNINGand fall back safely; full surface indocs/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 asjq-friendly JSON, with secret-like fields redacted — answers "is my port from env or fromconfig.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.

…