Skip to content
Back to search

BailoutMCP

Shadow-State frustration detector & silent heavy-model bailout trigger for AI coding agents — fuses local Ctrl+Z undo bursts, edit oscillations & recurring errors to quietly pre-solve exact surgical diffs via Opus, Gemini Pro, o3, Ollama or LiteLLM.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sunil56224972--bailoutmcp/badge.svg)](/listings/sunil56224972--bailoutmcp)

HTML

<a href="/listings/sunil56224972--bailoutmcp"><img src="/api/listings/sunil56224972--bailoutmcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Clone, Install, Build & Test

git clone https://github.com/Sunil56224972/BailoutMCP.git
cd BailoutMCP
pnpm install
pnpm run build
pnpm run test

2. Configure Your Real Heavy-Model Provider

Copy `.env.example` to `.env` (in your workspace root or `~/.bailout-mcp/.env`) and add **at least one** real provider:

cp .env.example .env

Example `.env` (Anthropic Opus primary, Gemini Pro fallback):

BAILOUT_PROVIDER=anthropic
BAILOUT_FALLBACK_PROVIDERS=gemini
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...

Verify provider readiness & security configuration:

pnpm run doctor

3. Connect BailoutMCP to Claude Code / Cursor / Windsurf / Antigravity

Generate your local `.bailout.json` and exact MCP JSON snippet:

node packages/mcp-server/dist/src/cli.js init

Add to your MCP client configuration:

{
  "mcpServers": {
    "bailout": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/BailoutMCP/packages/mcp-server/dist/src/cli.js"],
      "env": {
        "BAILOUT_PROVIDER": "anthropic",
        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
      }
    }
  }
}

> When the MCP server starts, it automatically connects to an existing local bridge or starts one on `127.0.0.1:47821` (with ephemeral port fallback on collision) so VS Code, Cursor, and Claude Code hooks share the exact same live Shadow-State.

4. Enable the VS Code / Cursor Companion Extension (Optional)

1. Open `packages/vscode-extension` in VS Code or Cursor and press `F5` (or build a `.vsix` package). 2. It auto-discovers `~/.bailout-mcp/bridge.json` and shows a subtle Status Bar pill: - `Flow (0)` — calm coding (long dwell without errors never triggers false alarms) - `Shadow: 58/100` — elevated undo/error friction - `Bailout Solving (78)` — silently running heavy reasoning model in background - `Bailout Ready (94%)` — validated diff waiting cleanly for a natural pause or click

5. Enable Claude Code Hooks & Skill (Optional)

- Merge [`hooks/claude-code/settings.snippet.json`](hooks/claude-code/settings.snippet.json) into `~/.claude/settings.json`. - Copy [`skills/bailout-detector/SKILL.md`](skills/bailout-detector/SKILL.md) into your agent skills directory.

6. CLI Mode (Zero IDE Extension Required)

# Run standalone local bridge daemon + file-save churn & oscillation watcher
node packages/mcp-server/dist/src/cli.js daemon --watch .

# Inspect live Shadow-State
node packages/mcp-server/dist/src/cli.js status

# Run an immediate secret-redacted heavy-model escalation on a stubborn file
node packages/mcp-server/dist/src/cli.js escalate ./src/buggyFile.ts --error "TypeError: ..."

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 250 lines
  1. <div align="center">
  2. # 🛟 BailoutMCP
  3. ### Shadow-State Frustration Detector & Silent Pre-Solved Heavy-Model Bailout Trigger
  4. **Stop waiting until you're furious to switch models.**
  5. BailoutMCP detects when you (or a fast coding model) are silently trapped in an undo/oscillation/error loop, quietly escalates a secret-redacted micro-context to a frontier reasoning model, validates the surgical diff, and offers it **only during a natural micro-pause**.
  6. [![CI](https://github.com/Sunil56224972/BailoutMCP/actions/workflows/ci.yml/badge.svg)](https://github.com/Sunil56224972/BailoutMCP/actions/workflows/ci.yml)
  7. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  8. [![Node.js >=20](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org)
  9. [![TypeScript](https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
  10. [![MCP Compatible](https://img.shields.io/badge/MCP-Stdio%20%2B%20Local%20Bridge-7C3AED)](https://modelcontextprotocol.io)
  11. [Why BailoutMCP](#-the-problem-nobody-solved) •
  12. [Architecture](#-architecture) •
  13. [Quick Start](#-quick-start) •
  14. [Providers](#-supported-heavy-model-providers) •
  15. [MCP Reference](#-mcp-tools-resources--prompts) •
  16. [Security Model](#-security--privacy-model)
  17. </div>
  18. ---
  19. ## 🔥 The Problem Nobody Solved
  20. Every developer using AI coding assistants hits the exact same wall every day:
  21. 1. You run a fast, affordable model (like Sonnet, Flash, or a local model) to preserve speed and quota.
  22. 2. You hit a tricky state, concurrency, or type bug. You spend **10+ minutes on the same file** — spamming `Ctrl+Z`, oscillating `A → B → A` on the same lines, hitting the same compiler/test error 4 times, while the lightweight model patches symptoms in circles.
  23. 3. **The AI has zero clue you're stuck** until you angrily type *"this still doesn't work, stop guessing!"* — and then you have to manually switch to Opus / Gemini Pro / o3 and re-explain everything from scratch.
  24. **BailoutMCP closes that loop silently in the background:**
  25. > *"Stuck on `CartCounter.tsx`? Escalated to `claude-opus-4-6` and validated a 1-line fix (94% confidence): 'Use functional React state updater to fix stale closure'. Review diff?"*
  26. - **100% Real Data & Real Models:** Zero fake/mock analyzers, zero hardcoded fallbacks. If no real model provider is configured, BailoutMCP honestly reports `routerReady: false`.
  27. - **Zero-Clippy Anti-Annoyance Gate:** Never pops up mid-keystroke. Waits silently for a natural micro-pause (`>= 3.5s` idle), auto-invalidates if you solve the bug yourself (**Micro-Win reset**), and backs off exponentially (`1x → 2x → 4x`) whenever dismissed.
  28. - **Privacy-First & Hardened:** Raw keystrokes are never logged or transmitted. Sensitive files (`.env*`, keys, `.ssh`, `.aws`, DBs) are strictly blocked, and secrets are scrubbed before any code snippet leaves your machine.
  29. ---
  30. ## ⚡ How It Differs From Existing Tools
  31. | Capability | Regex Frustration Checks | Proxy Stall Routers (LiteLLM / Advisor) | **BailoutMCP** |
  32. | :--- | :---: | :---: | :---: |
  33. | Detects frustration **before** you type an angry prompt | ❌ | ❌ | ✅ |
  34. | Tracks native `Ctrl+Z` undo bursts & `A→B→A` edit oscillation | ❌ | ❌ | ✅ |
  35. | Bridges **IDE behavioral signals** (VS Code/Cursor) with **CLI agents** (Claude Code) | ❌ | ❌ | ✅ |
  36. | Silently **pre-solves** & validates exact surgical diff in background | ❌ | ❌ | ✅ |
  37. | **Natural-pause timing gate** (never interrupts mid-typing) | ❌ | ❌ | ✅ |
  38. | **Micro-Win reset** (auto-clears friction & discards stale bailout when errors drop to 0) | ❌ | ❌ | ✅ |
  39. | Cross-provider heavy routing (Opus, Gemini Pro, o3, OpenRouter, Ollama, LiteLLM) | ❌ | Partial | ✅ |
  40. ---
  41. ## 🏗 Architecture
  42. ```mermaid
  43. flowchart LR
  44. subgraph Sensors["100% Local Structural Sensors (No Keylogging)"]
  45. IDE["VS Code / Cursor Extension\n• Native Ctrl+Z Undo/Redo\n• Edit Churn & A→B→A Hash\n• Debounced LSP Diagnostics\n• Terminal Non-Zero Exits"]
  46. HOOKS["Claude Code Hooks & Watcher\n• PostToolUse Exec Errors\n• Prompt Retry Signals\n• File-Save Churn Watcher"]
  47. end
  48. subgraph Bridge["@bailout-mcp/server (127.0.0.1 Token Auth + Host/CSRF Guard)"]
  49. SSE["HTTP + SSE Shared Telemetry Bus"]
  50. MCP["Stdio MCP Server\n7 Tools • 3 Resources • 1 Prompt"]
  51. end
  52. subgraph Core["@bailout-mcp/core"]
  53. SS["Shadow-State Scorer (0–100)\n+ Micro-Win Reset"]
  54. DIST["Context Distiller (±45 lines)\n+ Workspace Jail + Secret Redactor"]
  55. ROUTER["Universal Bailout Router\nOpus • Gemini Pro • o3 • Ollama • LiteLLM"]
  56. PATCH["Patch Validator + Safety Guard\nExact Line Anchor + Atomic Write"]
  57. GATE["Anti-Annoyance Timing Gate\nWaits for Natural Micro-Pause"]
  58. end
  59. IDE -->|X-Bailout-Token| SSE
  60. HOOKS -->|X-Bailout-Token| SSE
  61. SSE --> SS
  62. MCP --> SS
  63. SS -->|score >= 70| DIST
  64. DIST --> ROUTER
  65. ROUTER --> PATCH
  66. PATCH --> GATE
  67. GATE -->|SSE Toast / Diff| IDE
  68. GATE -->|Hook / MCP Tool| MCP
  69. ```
  70. ### Monorepo Layout
  71. | Package / Path | Purpose |
  72. | :--- | :--- |
  73. | [`packages/core`](packages/core) | Zero-dependency TypeScript core: Shadow-State scorer, error signature normalizer, secret redactor, security jail, context distiller, universal model router, surgical patcher, and pause timing gate |
  74. | [`packages/mcp-server`](packages/mcp-server) | Stdio MCP server (`@modelcontextprotocol/sdk`), hardened `127.0.0.1` HTTP/SSE bridge daemon, CLI workspace churn watcher, `doctor`, `escalate`, `status`, and `init` commands |
  75. | [`packages/vscode-extension`](packages/vscode-extension) | Thin VS Code / Cursor companion extension with calm Status Bar HUD, native side-by-side `vscode.diff` viewer, and `Ctrl+Z`-undoable 1-click `WorkspaceEdit` apply |
  76. | [`hooks/claude-code`](hooks/claude-code) | Non-blocking `PostToolUse` & `UserPromptSubmit` hooks that stream agent loops and inject pre-solved heavy-model rescues directly into Claude Code |
  77. | [`skills/bailout-detector`](skills/bailout-detector/SKILL.md) | Standard Agent Skill (`SKILL.md`) teaching coding agents how to report loops, check `bailout://shadow-state`, and surface rescues calmly |
  78. ---
  79. ## 🚀 Quick Start
  80. ### 1. Clone, Install, Build & Test
  81. ```bash
  82. git clone https://github.com/Sunil56224972/BailoutMCP.git
  83. cd BailoutMCP
  84. pnpm install
  85. pnpm run build
  86. pnpm run test
  87. ```
  88. ### 2. Configure Your Real Heavy-Model Provider
  89. Copy `.env.example` to `.env` (in your workspace root or `~/.bailout-mcp/.env`) and add **at least one** real provider:
  90. ```bash
  91. cp .env.example .env
  92. ```
  93. Example `.env` (Anthropic Opus primary, Gemini Pro fallback):
  94. ```dotenv
  95. BAILOUT_PROVIDER=anthropic
  96. BAILOUT_FALLBACK_PROVIDERS=gemini
  97. ANTHROPIC_API_KEY=sk-ant-...
  98. GEMINI_API_KEY=AIza...
  99. ```
  100. Verify provider readiness & security configuration:
  101. ```bash
  102. pnpm run doctor
  103. ```
  104. ### 3. Connect BailoutMCP to Claude Code / Cursor / Windsurf / Antigravity
  105. Generate your local `.bailout.json` and exact MCP JSON snippet:
  106. ```bash
  107. node packages/mcp-server/dist/src/cli.js init
  108. ```
  109. Add to your MCP client configuration:
  110. ```json
  111. {
  112. "mcpServers": {
  113. "bailout": {
  114. "command": "node",
  115. "args": ["/ABSOLUTE/PATH/TO/BailoutMCP/packages/mcp-server/dist/src/cli.js"],
  116. "env": {
  117. "BAILOUT_PROVIDER": "anthropic",
  118. "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}"
  119. }
  120. }
  121. }
  122. }
  123. ```
  124. > When the MCP server starts, it automatically connects to an existing local bridge or starts one on `127.0.0.1:47821` (with ephemeral port fallback on collision) so VS Code, Cursor, and Claude Code hooks share the exact same live Shadow-State.
  125. ### 4. Enable the VS Code / Cursor Companion Extension (Optional)
  126. 1. Open `packages/vscode-extension` in VS Code or Cursor and press `F5` (or build a `.vsix` package).
  127. 2. It auto-discovers `~/.bailout-mcp/bridge.json` and shows a subtle Status Bar pill:
  128. - `Flow (0)` — calm coding (long dwell without errors never triggers false alarms)
  129. - `Shadow: 58/100` — elevated undo/error friction
  130. - `Bailout Solving (78)` — silently running heavy reasoning model in background
  131. - `Bailout Ready (94%)` — validated diff waiting cleanly for a natural pause or click
  132. ### 5. Enable Claude Code Hooks & Skill (Optional)
  133. - Merge [`hooks/claude-code/settings.snippet.json`](hooks/claude-code/settings.snippet.json) into `~/.claude/settings.json`.
  134. - Copy [`skills/bailout-detector/SKILL.md`](skills/bailout-detector/SKILL.md) into your agent skills directory.
  135. ### 6. CLI Mode (Zero IDE Extension Required)
  136. ```bash
  137. # Run standalone local bridge daemon + file-save churn & oscillation watcher
  138. node packages/mcp-server/dist/src/cli.js daemon --watch .
  139. # Inspect live Shadow-State
  140. node packages/mcp-server/dist/src/cli.js status
  141. # Run an immediate secret-redacted heavy-model escalation on a stubborn file
  142. node packages/mcp-server/dist/src/cli.js escalate ./src/buggyFile.ts --error "TypeError: ..."
  143. ```
  144. ---
  145. ## 🧠 Supported Heavy-Model Providers
  146. | Provider (`BAILOUT_PROVIDER`) | Env / Config | Default Model | Notes |
  147. | :--- | :--- | :--- | :--- |
  148. | `anthropic` | `ANTHROPIC_API_KEY` | `claude-opus-4-6` | Native Messages API |
  149. | `gemini` | `GEMINI_API_KEY` | `gemini-2.5-pro` | `x-goog-api-key` header + JSON schema mime output |
  150. | `openai` | `OPENAI_API_KEY` | `o3` | Auto-detects `o1`/`o3`/`o4` (`max_completion_tokens`, omits `temperature`) |
  151. | `openrouter` | `OPENROUTER_API_KEY` | `anthropic/claude-opus-4.6` | Unified multi-model routing |
  152. | `ollama` | `BAILOUT_OLLAMA_URL`, `BAILOUT_OLLAMA_MODEL` | `qwen2.5-coder:32b` | 100% local offline real reasoning LLM |
  153. | `custom` | `BAILOUT_ROUTER_URL`, `BAILOUT_ROUTER_MODEL` | *(your router)* | Works with LiteLLM / custom proxies; sends `X-Bailout-Trigger: shadow-state`, `X-Bailout-Frustration-Score`, `X-Bailout-Original-Model` |
  154. Set `BAILOUT_FALLBACK_PROVIDERS=gemini,openrouter` to enable automatic failover across providers.
  155. ---
  156. ## 🛠 MCP Tools, Resources & Prompts
  157. ### Tools
  158. | Tool | Description |
  159. | :--- | :--- |
  160. | `get_shadow_state` | Live frustration score (`0–100`), phase, provider readiness, primary hotspot, signal breakdown, timing gate status, and stats |
  161. | `record_signal` | Ingest `undo_burst`, `edit_churn`, `file_dwell`, `diagnostic_error`, `terminal_error`, `agent_tool_error`, `prompt_abandoned`, or `error_resolved` |
  162. | `get_pending_bailout` | Retrieve silently pre-solved heavy-model fix, root cause, confidence, and unified diff |
  163. | `trigger_bailout` | Explicitly distill a redacted dossier and escalate a workspace file to the configured heavy model |
  164. | `accept_bailout` | Accept proposal (optionally applying the validated surgical patch atomically to disk) and clear friction |
  165. | `dismiss_bailout` | Dismiss pending fix and apply exponential cooldown backoff (`1x → 2x → 4x`) |
  166. | `configure_bailout_router` | Safely tune runtime thresholds or switch between already-configured providers (never exposes/mutates keys or URLs) |
  167. ### Resources & Prompts
  168. - `bailout://shadow-state` — Real-time Shadow-State snapshot JSON
  169. - `bailout://pending-bailout` — Pre-solved heavy-model bailout proposal + unified diff
  170. - `bailout://last-dossier` — Exact secret-redacted context window sent to the heavy model (full transparency)
  171. - `present-bailout` — Prompt template for calm, 2-sentence + diff presentation
  172. ---
  173. ## 🔒 Security & Privacy Model
  174. BailoutMCP is engineered for real professional codebases from day one:
  175. | Threat Vector | Defense Implemented |
  176. | :--- | :--- |
  177. | **Keystroke Spyware Concerns** | Raw keystrokes are **never** recorded or sent. The VS Code companion reads only structural events (`TextDocumentChangeReason.Undo/Redo`, line ranges, non-reversible SHA-256 region hashes, debounced diagnostics, exit codes). |
  178. | **Credential / Secret Leakage** | Sensitive files (`.env*`, `*.pem`, `*.key`, `id_rsa*`, `.ssh/*`, `.aws/*`, `.npmrc`, `credentials.json`, `bridge.json`, `*.sqlite`, OS system dirs) are strictly blocked. An automated redactor scrubs API keys (Anthropic, OpenAI, Google, OpenRouter, Stripe, GitHub, Slack, SendGrid, HF, npm, AWS), JWTs, Basic/Bearer auth, PEM blocks, and DB URI passwords before egress. |
  179. | **Path Traversal & Symlink Escape** | Symlink-resolved `assertSafeWorkspacePath` enforces workspace boundaries on both dossier reads and atomic disk writes. |
  180. | **Localhost DNS Rebinding & CSRF** | Bridge binds strictly to `127.0.0.1`, verifies a 48-hex-char random token (`0600`) using `crypto.timingSafeEqual` in `X-Bailout-Token` header only (URL query tokens rejected), validates strict `Host` headers (`403`), and rejects browser `Origin` headers (`403`). |
  181. | **SSRF & Runtime Hijacking** | `validateEndpointUrl` blocks AWS/GCP metadata IPs (`169.254.169.254`, `metadata.google.internal`), RFC1918 private IPs, `0.0.0.0`, IPv6 link-local/ULA, embedded URL credentials, `file://`, and non-loopback plaintext `http://`. MCP/HTTP config calls cannot mutate API keys, `baseUrl`, or `allowedWorkspaceRoots`. |
  182. | **Prompt Injection in Untrusted Repos** | Untrusted workspace code and logs are isolated inside per-request random nonce delimiters (`<UNTRUSTED_CODE_nonce>`). `validatePatchSafety` rejects oversized rewrites (`> 35` lines) and newly-introduced dangerous primitives (`eval()`, `new Function()`, `child_process`, `fs.rmSync`, remote `import()`, piped shell downloads, encoded PowerShell). |
  183. | **Runaway API Spend** | Single-flight solve lock, `AbortSignal.timeout(45s)`, minimum confidence filter (`>= 0.72`), hard hourly (`6/hr`) & daily (`25/day`) caps, and per-file cooldowns. |
  184. ---
  185. ## 📄 License
  186. Released under the [MIT License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.