AI Intervention Agent

AI Intervention Agent

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

PyPI Python versions MCP Compatible Tests OpenSSF Scorecard License: MIT

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

Install in Cursor Install in VS Code

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, code highlighting, 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, question_type='yesno' one-click decisions, and feedback_placeholder hints
  • 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)

Open VSX version Open VSX downloads Open VSX rating

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

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

Project links

Data verified by PyPI on Jul 26, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.8.9)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for xiadengma from gravatar.com xiadengma

Credits

Author: xiadengma

GitHub Statistics

Data verified by PyPI on Jul 26, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

dev

Tags

agent ai claude cursor feedback intervention mcp

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ai_intervention_agent-1.8.8.tar.gz (3.4 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

ai_intervention_agent-1.8.8-py3-none-any.whl (3.5 MB view details)

Uploaded Python 3

File details

Details for the file ai_intervention_agent-1.8.8.tar.gz.

File metadata

  • Download URL: ai_intervention_agent-1.8.8.tar.gz
  • Upload date:
  • Size: 3.4 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for ai_intervention_agent-1.8.8.tar.gz
Algorithm Hash digest
SHA256 41f4395c745dce39b277a6aa0564b344962c008baf93c67f960514778fc28001
MD5 d2aaed9cfdb87a7adfd81d9d15cf9df2
BLAKE2b-256 faefa0895decdf101d84ca0268b76c7c131930b120ae33114feb4aacc69c0760

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_intervention_agent-1.8.8.tar.gz:

Publisher: release.yml on XIADENGMA/ai-intervention-agent

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ai_intervention_agent-1.8.8-py3-none-any.whl.

File metadata

File hashes

Hashes for ai_intervention_agent-1.8.8-py3-none-any.whl
Algorithm Hash digest
SHA256 08027a97ae717bd52dae43811daf65e6e3d72e8444ef70f135a87125a7bcf637
MD5 c18a1090641eeb6b70b345a44d3231a4
BLAKE2b-256 949f18f95889027a0cd369cbfed39decb5ddfeb19817b7854526af6e7e3a1655

See more details on using hashes here.

Provenance

The following attestation bundles were made for ai_intervention_agent-1.8.8-py3-none-any.whl:

Publisher: release.yml on XIADENGMA/ai-intervention-agent

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.8.9

2 files

This release

1.8.8 This release

2 files

1.8.7

2 files

1.8.6

2 files

1.8.3

2 files

1.8.2

2 files

1.7.13

2 files

1.7.11

2 files

1.7.9

2 files

1.7.8

2 files

1.7.7

2 files

1.7.6

2 files

1.7.4

2 files

1.7.3

2 files

1.7.2

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.36

2 files

1.5.35

2 files

1.5.34

2 files

1.5.33

2 files

1.5.26

2 files

1.5.25

2 files

1.5.24

2 files

1.5.22

2 files

1.5.19

2 files

1.5.18

2 files

1.5.17

2 files

1.5.15

2 files

1.5.13

2 files

1.5.9

2 files

1.5.8

2 files

1.5.6

2 files

1.5.5

2 files

1.5.4

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.17

2 files

1.4.16

2 files

1.4.15

2 files

1.4.14

2 files

1.4.13

2 files

1.4.12

2 files

1.4.10

2 files

1.4.9

2 files

1.4.8

2 files

1.4.7

2 files

1.4.6

2 files

1.4.5

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.3.2

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page