ai-intervention-agent 1.7.6

AI Intervention Agent: MCP server enabling real-time user intervention in AI-assisted development workflows.

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

Quickest: ask your AI to install it for you

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

Click to copy the install prompt

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.

Option 1: Using uvx (Recommended)

Configure your AI tool to launch the MCP server directly via uvx (this automatically installs and runs the latest version):

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

Option 2: Using pip

1. First, install the package manually (please remember to manually pip install --upgrade ai-intervention-agent periodically to get updates):

pip install ai-intervention-agent

2. Configure your AI tool to launch the installed MCP server:

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

[!NOTE] interactive_feedback is a long-running tool. Some clients have a hard request timeout, so the Web UI provides a countdown + auto re-submit option to keep sessions alive.

• Default: feedback.frontend_countdown=240 seconds
• Range: 0 (disabled) or [10, 3600] seconds. The default 240 stays under the common 300s session hard timeout; raise it intentionally when your client allows longer turns.

3. (Optional) Customize your config:

• On first run, config.toml will be created under your OS user config directory (see docs/configuration.md).
• Example:

[web_ui]
port = 8080

[feedback]
frontend_countdown = 240
backend_max_wait = 600

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

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 — switch between concurrent requests, each with its own countdown
• 🔁 Auto re-submit — keep long-running sessions alive past client hard timeouts
• 🔔 Notifications — web / sound / system / Bark (loopback URLs auto-suppressed; LAN-IP suggestion in settings)
• 🌐 SSH / LAN friendly — works behind port forwarding; mDNS publishes a <host>.local URL when supported

Architecture diagram, "how it works" flow, production middleware chain, server self-info resource, and MCP-spec compliance details live under docs/api/index.md and docs/mcp_tools.md.

VS Code extension (optional)

Item	Value
Purpose	Embed the interaction panel into VS Code’s sidebar to avoid switching to a browser.
Install (Open VSX)	Open VSX
Download VSIX (GitHub Release)	GitHub Releases
Setting	ai-intervention-agent.serverUrl (should match your Web UI URL, e.g. http://localhost:8080; you can change web_ui.port in config.toml.default)
Other settings	ai-intervention-agent.logLevel (Output → AI Intervention Agent). macOS native notifications are enabled by default and can be toggled in the sidebar's Notification Settings panel. See packages/vscode/README.md for the full settings list and the AppleScript executor security model.

Configuration

Item	Value
Docs (English)	docs/configuration.md
Docs (简体中文)	docs/configuration.zh-CN.md
Default template	config.toml.default (on first run it will be copied to config.toml)

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

Quick overrides (no file edits required)

For uvx, Docker, systemd, or SSH-remote runtimes where editing config.toml is awkward, the most-used web_ui settings can be overridden by env var at process startup:

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
uvx ai-intervention-agent

Invalid values log a WARNING and fall back to config.toml/defaults so a typo never blocks server startup. See docs/configuration.md#environment-variable-overrides for the full surface (timeouts, log level, etc.).

CLI inspection

ai-intervention-agent --version       # or -V — print version and exit
ai-intervention-agent --help          # or -h — show usage + config hints
ai-intervention-agent --print-config  # dump effective merged config + env overrides

--print-config answers "is my port 8181 because of env, or config.toml?" in one shell pipeline — output is JSON (jq friendly):

• config_file_path — absolute path of the loaded TOML
• using_defaults — true if the loaded file is the bundled default (i.e. you haven't created your own config.toml yet)
• web_ui — resolved host / port / language (back-compat top-level)
• sections — every non-sensitive section (web_ui / mdns / feedback / notification); secret-like fields (*_device_key, *_token, *_secret, password, *_api_key, …) auto-redacted to ***REDACTED***
• env_overrides — active AI_INTERVENTION_AGENT_WEB_UI_* env vars

network_security is filtered out at the ConfigManager.get_all() boundary (same trust level as /api/system/health), so monitoring and CLI tell the same story.

Documentation

• Docs index (by audience): docs/README.md · docs/README.zh-CN.md
• Scripts index (CI gates / generators / QA): scripts/README.md
• Release notes: CHANGELOG.md · VS Code marketplace listing: packages/vscode/CHANGELOG.md
• Contributing: CONTRIBUTING.md · CODE_OF_CONDUCT.md
• API docs index: docs/api/index.md
• API docs (简体中文): docs/api.zh-CN/index.md
• MCP tool reference: docs/mcp_tools.md
• MCP 工具说明: docs/mcp_tools.zh-CN.md
• Troubleshooting / FAQ: docs/troubleshooting.md · docs/troubleshooting.zh-CN.md
• Release recovery runbook: docs/release-recovery.md · docs/release-recovery.zh-CN.md
• i18n contributor guide: docs/i18n.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. Dual-interface (Web UI + Tauri desktop app), auto-command execution, intelligent SSH Remote / WSL detection. Supports Cursor / Cline / Windsurf / Augment / Trae.
cunzhi (imhuso)	~1.4k	Chinese-language project focused on preventing premature task completion ("告别 AI 提前终止烦恼").
interactive-feedback-mcp (poliva)	~310	Direct ancestor fork (rebased from noopstudios original — see Acknowledgements below); 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 the same backend, production-grade observability (/metrics Prometheus endpoint + a reference Grafana dashboard, SSE schema validation toggle), bilingual i18n + docs, strict invariant test discipline (5,500+ tests + ~700 subtests), pre-push tag-safety hook, and a 6-job release pipeline. If you want the smallest possible drop-in, poliva's fork; if you want a polished desktop app, mcp-feedback-enhanced; if you want full-stack operational integration, AIIA.

Star counts are approximate snapshots (last reviewed 2026-05); 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

---

Quality & Security

• Tests — GitHub Actions test workflow status (runs on every push / PR)
• OpenSSF Scorecard — supply-chain security posture
• Python versions — supported runtime compatibility (declared in pyproject.toml)