ai-intervention-agent

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

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 (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"]`
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

Desktop - feedback page (multi-task tabs, Markdown table, code highlighting, math, predefined options) Mobile - feedback page

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

More screenshots (empty state + settings)

Desktop - empty state Mobile - empty state

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

Desktop - settings (notifications, Bark, feedback) Mobile - settings

_{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)
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:

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      # 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

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)	~50	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 — 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

Metadata

Release files for ai-intervention-agent 1.8.11

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai-intervention-agent 1.8.11
File	Size	Uploaded
ai_intervention_agent-1.8.11.tar.gz	2.8 MB	Sep 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ai-intervention-agent 1.8.11
File	Interpreter	ABI	Platform	Reset
ai_intervention_agent-1.8.11-py3-none-any.whl 2.9 MB Sep 7, 2026	Python 3	none	any	Details

Total release size: 5.7 MB

Release files / ai_intervention_agent-1.8.11.tar.gz

Download URL	ai_intervention_agent-1.8.11.tar.gz
Size	2.8 MB
Tags	Source
SHA-256 checksum How to use checksums	`da1ac049d126c0dff70ac8686aea30ff2b132f5f4d1de69bdb2df66f5f830fdb`
BLAKE2b-256 checksum How to use checksums	`8af91933c6fcf03864a0a0b64a82cc8e553e4ac9d340e25d5b787a25036f9c6b`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/XIADENGMA/ai-intervention-agent
Publishing commit: github.com/XIADENGMA/ai-intervention-agent/tree/9accb12cfb51cdcaed10df11cc9a4f521a630326

Workflow

Publishing configuration: github.com/XIADENGMA/ai-intervention-agent/blob/9accb12cfb51cdcaed10df11cc9a4f521a630326/.github/workflows/release.yml
Publishing logs: github.com/XIADENGMA/ai-intervention-agent/actions/runs/34083952700/attempts/1

Artifact

Subject: ai_intervention_agent-1.8.11.tar.gz
SHA-256 checksum: da1ac049d126c0dff70ac8686aea30ff2b132f5f4d1de69bdb2df66f5f830fdb Verifying attestations

Release files / ai_intervention_agent-1.8.11-py3-none-any.whl

Download URL	ai_intervention_agent-1.8.11-py3-none-any.whl
Size	2.9 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`3bf34703276a2a33ed1daaee06f3258a3a6ed1519aeeec5637db80891bc4bc74`
BLAKE2b-256 checksum How to use checksums	`916f85e3aefc1e03ce88f7f793128ddc1db14d24a3ee07242744c7c93e8270b6`
Upload date	Sep 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/XIADENGMA/ai-intervention-agent
Publishing commit: github.com/XIADENGMA/ai-intervention-agent/tree/9accb12cfb51cdcaed10df11cc9a4f521a630326

Workflow

Publishing configuration: github.com/XIADENGMA/ai-intervention-agent/blob/9accb12cfb51cdcaed10df11cc9a4f521a630326/.github/workflows/release.yml
Publishing logs: github.com/XIADENGMA/ai-intervention-agent/actions/runs/34083952700/attempts/1

Artifact

Subject: ai_intervention_agent-1.8.11-py3-none-any.whl
SHA-256 checksum: 3bf34703276a2a33ed1daaee06f3258a3a6ed1519aeeec5637db80891bc4bc74 Verifying attestations