ctrl-alt-pray
This MCP server acts as a circuit breaker for AI coding agents, forcing ground-truth diagnostics via pray() when loops occur.
Halt circular edits after 2 failed attempts and block further code changes until a diagnostic probe runs.
Call
pray()to auto-harvest git status, lockfiles, occupied ports, and error logs for ground truth.Receive one of 12 canonical recovery recipes (e.g., stale build, port zombie, hallucinated API) with a bounded sanity check.
Report experiment outcomes (
supports,contradicts,inconclusive,blocked) to advance a recovery decision ledger.Inspect a recovery session ledger read-only without mutating state or advancing revision.
Manage sessions with
project_key,session_id,expected_revision, and idempotentrequest_idfor concurrency control.Configure constraints, capabilities, observations, hypotheses, budget, heresy mode, and adversarial second opinions.
Track cost (tokens, tool calls, duration) and verification checks, changes, and new observations.
Enforce hard OS-level constraints (e.g.,
pray-runkills hung processes >15s) rather than relying on prompts.Store all evidence locally in SQLite WAL with zero external telemetry and zero runtime dependencies.
Integrates with Windsurf (Codeium) by auto-detecting the workspace and arming the circuit breaker and MCP configuration, enabling the AI agent to use the pray tool to break debugging loops.
Integrates with JetBrains AI by provisioning MCP configuration and rules, enabling the IDE's AI agent to invoke the pray tool for sanity checks and loop prevention.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ctrl-alt-pray the AI failed twice, gather evidence and suggest a fix"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🕯️ Ctrl Alt Pray
When Ctrl+Z isn't enough. Pray.
The open-source anti-loop circuit breaker for Cursor, Claude Code, Cline, and autonomous coding agents.
Halt circular edits. Kill zombie terminals. Force your AI to check reality before burning your API budget.
🕯️ THE ALTAR OF GROUND TRUTH HAS BEEN SUMMONED 🕯️
[ PRAYERS ARE OPTIONAL. FALSIFIABLE EVIDENCE IS REQUIRED. ]🌐 Live Website & Simulator • ⭐ Star on GitHub • 📚 Articles Hub • Quickstart in 10s • Why Pray? • 5 Real Practice Traps • The 12 Canonical Rites
💡 What Is This In 10 Seconds?
You give an autonomous AI agent (Cursor, Claude Code, Cline, etc.) a failing test to fix.
Attempt 1 fails. Attempt 2 fails.
Instead of stopping, your agent enters The 3:00 AM Doom Loop:
It apologizes profusely ("I apologize for the confusion! Let me fix that!").
It tweaks random lines of code, reverts its own previous edits, and tweaks them again.
It burns $20 in tokens while the true bug was a stale build cache or a deadlocked port 3000.
ctrl-alt-pray fixes this with 3 ironclad rules:
The 2-Strikes Circuit Breaker: If the AI fails twice on the same check, it is strictly barred from editing code.
The
pray()MCP Tool: The AI is forced to callpray(). The tool scans git status, locked ports, and error logs, and prescribes ONE bounded sanity check instead of another blind guess.The Terminal Guardian (
pray-run): If a background test watcher or process freezes for >15 seconds, it kills the entire process tree (SIGKILL) to reclaim your dev ports.
Related MCP server: jev-harness
🕯️ Why "Pray"? (The Developer Story Behind The Name)
Every engineer who has stayed up until 3:00 AM watching an AI agent hallucinate across 20 files knows this feeling:
You tried Ctrl+C. You tried Ctrl+Z. You tried rewriting your prompt. Nothing worked.
You put your head in your hands and literally whispered:
"Please God, just let this build pass."
We turned that developer despair into an open-source engineering tool.
How pray Actually Works In Practice
When your AI hits the 2-failure limit, the injected rule tells it:
"STOP editing code. Invoke the pray tool."
The AI literally calls:
{
"tool": "pray",
"arguments": {
"error": "Expected 200, received 401",
"failed_attempts": 2
}
}When pray is invoked, it forces the agent to take a breath:
Silences the Apology Tax: The AI is forbidden from generating polite placating filler. Apologizing costs tokens and pollutes the context window.
Checks Physical Reality: The tool inspects uncommitted git churn, occupied ports (
:3000,:5173), and test artifacts.Returns Ground Truth: The tool dispenses 1 of 12 proven diagnostic recipes (e.g., "Stop editing
src/. You forgot to rebuilddist/.").Resets the Search Space: The agent runs one atomic check, discovers the actual root cause, and fixes it in 1 clean commit.
🛠️ 5 Real Traps That Break AI Agents In Practice
Here are the exact daily failure modes where autonomous agents burn your money—and how pray() resolves each in seconds:
Trap 1: The Stale Build Mirage (Editing src/, testing dist/)
The Pain: The AI edits
src/auth.ts, runspnpm test, and fails. The AI assumes its logic was wrong, so it rewrites the file 5 times. But the test runner was executing stale code indist/auth.jsbecause nobody ranpnpm build! The agent burns 40,000 tokens editing the right file for the wrong reason.How
prayFixes It:pray()dispenses Recipe 01: Exposing the False Idol. It injects a unique diagnostic marker into source. When the marker is absent from stdout, it immediately informs the agent: "Your code edits produce zero change in test output. You are editing source while tests run against stale dist. Run build first."
Trap 2: The Port Zombie (Port 3000 locked by orphaned PID)
The Pain: An earlier test run spawned a background Vite server or test watcher. It hung silently. The next turn, the agent tries to run the server and gets
EADDRINUSE: port 3000 already in use. The agent hallucinates and changes the port to 3001 in config, breaking frontend-backend contracts and creating configuration drift.How
prayFixes It:pray-runterminates commands that hang >15s without output. Whenpray()is called, its Harvester probes standard dev ports (3000,5173,8080), identifies the orphan process, and runs a cascade kill tree (SIGKILL -9) to release the socket in <100ms.
Trap 3: The Apology & Guesswork Spiral
The Pain: "I apologize! Let me inspect the PostgreSQL balance schema..." "My mistake, let me revert and rewrite the cookie parser..." Every turn, the AI spends 1,500 tokens apologizing and spinning up elaborate new explanations for a problem it doesn't understand.
How
prayFixes It: The tripwire penalizes conversational filler and bans apologies. In the live Altar HUD, apologies incur an instant -25 point Epistemic Karma penalty (Dire Wrath). The model is strictly barred from modifying code until it executes an isolated diagnostic probe.
Trap 4: The Poison Chalice (Swallowed Assertions / False Green)
The Pain: A developer reports a bug in checkout. The AI tweaks a file and runs tests. The test suite reports green (PASS). The AI declares: "Bug is fixed!" But in reality, an unhandled
try/catchin a test helper swallowed the exception, giving a false green while production remains broken.How
prayFixes It:pray()dispenses Recipe 02: The Poison Chalice. It instructs the agent to inject a deliberate failing assertion (assert(1 === 2)) inside the checkout path. When the test still passes, the agent proves the test is broken before shipping fake fixes to production.
Trap 5: The Hallucinated Method Loop
The Pain: The AI tries calling
client.getUser(). Fails withTypeError: client.getUser is not a function. It guessesclient.fetchUser(). Fails. It guessesclient.findUser(). Fails. It tries to invent polyfills instead of checking the library's actual exports.How
prayFixes It:pray()dispenses Recipe 04: Rite of True Vision. It commands the agent to execute a 1-line runtime reflection script:node -e "import('pkg').then(m => console.log(Object.keys(m)))". The true method names are reflected in 50ms.
⚡ 10-Second Quickstart
1. Provision Your Editor (1-Click CLI Auto-Ignition)
Run this command in the root of your project:
npx ctrl-alt-pray initThis auto-detects your workspace and provisions the 2-Strikes Circuit Breaker and local MCP configuration:
Editor / Agent | 1-Click Direct Link | CLI Command | Files Armed |
Cursor |
|
| |
VS Code / Copilot |
|
| |
Claude Code | Native CLI Hook |
|
|
Windsurf (Codeium) | Auto-detected |
|
|
Cline & Roo Code | Auto-detected |
|
|
Zed Editor | Auto-detected |
|
|
JetBrains AI | Auto-detected |
|
|
Google Antigravity | Auto-detected |
|
|
2. Wrap Commands With Active Terminal Guardian (pray-run)
Stop letting processes freeze silently. Wrap test or build runs:
pray-run pnpm test
# or
pray-run npm run buildIf a command hangs for >15s with zero output (e.g. waiting on a hidden (y/n)? prompt), pray-run terminates the process tree automatically and outputs the unblocking action.
📜 The 12 Canonical Recovery Recipes
When an agent invokes pray(), the engine matches symptoms against 12 version-controlled, battle-tested recovery recipes:
# | Recipe Key | Trigger Symptom | Prescribed Ground-Truth Action | Safety Guarantee |
01 |
| Code edits produce zero change in test output; identical error | Inject unique runtime marker ( | Harmless print; zero mutation |
02 |
| Tests stay green despite reported bug; missing logs | Introduce deliberate failing assertion ( | Temporary negative control |
03 |
| Command hung >15s; pipe EOF deadlock; unhandled prompt | Inspect CPU% & process tree; cascade kill if 0% CPU with frozen log | Read-only inspection; cascade kill |
04 |
|
| Run 1-line script: | Read-only runtime reflection |
05 |
| $\ge 4$ uncommitted files; stacked messy diffs |
| Safely stashes uncommitted work |
06 |
|
| Verify binary path ( | Read-only host environment triage |
07 |
| Candidate hypothesis treated as fact without proof | Execute a single diagnostic probe designed strictly to disprove it | Low-risk assertion or query |
08 |
| Huge 10MB payload; 200 fields; noisy repro | Halve input payload repeatedly until atomic failure invariant remains | Isolated local test fixture |
09 |
| Regression between commits or multi-step pipeline break | Inspect and log payload state exactly midway between entry and failure | Read-only intermediate logging |
10 |
| Two plausible causes separated by known-good input | Hold all variables constant and swap suspect component with verified twin | Local temporary swap |
11 |
| Subsystem boundary unclear; ambiguous stack trace | Compare inputs and outputs across component boundary before editing code | Zero mutation boundary check |
12 |
| Ambiguous product requirement; conflicting business spec | Formulate one concrete multiple-choice question to the human maker | Zero speculative guessing |
📊 Local Evidence Ledger & Telemetry
Inspect Intercepted Loops
All intercepted loops and token savings are logged locally with zero external telemetry:
# View summary statistics in your terminal:
pray stats
# Launch the visual ledger dashboard (http://127.0.0.1:3900):
ctrl-alt-pray dashboardStorage: SQLite WAL mode in
~/.ctrl-alt-pray/sessions.sqlite.Privacy: 100% offline. Zero remote telemetry. Zero analytics tracking.
⚖️ Why Developers Star This
Zero Runtime Dependencies: Built entirely with native Node.js APIs (
node:net,node:child_process,node:sqlite). Fast startup (<5ms).Hard OS Constraints Over Soft Prompts: Prompts alone cannot detect occupied sockets or kill orphaned worker processes.
ctrl-alt-prayenforces real operating system boundaries.Context Window Saver: Cuts 20-turn circular apology loops into a 1-step resolution, saving tens of thousands of tokens per debugging session.
When Ctrl+Z isn't enough. Pray.
Built with pragmatism by Hoang Yell • Licensed under ISC
Available Tools
3 toolsinspect_ledgerA
Read-only inspection of a recovery session ledger without mutating state or advancing revision.
Inputs: session_id (required), project_key (required).
prayA
Summon the Altar of Ground Truth when standard debugging fails or repetitive loops occur. CALL THIS TOOL IMMEDIATELY WHEN: (1) A test or command fails 2+ times with similar errors; (2) An edited code change produced zero difference in output; (3) A terminal command or child process hangs/times out >15s; (4) You are guessing module exports or APIs; (5) You feel the urge to apologize for failed attempts. If auto_harvest is true (default), scans git status, lockfiles, and occupied ports automatically.
Inputs: budget, problem, attempts, request_id, +11 more.
report_outcomeC
Record the empirical result of an experiment and advance the recovery decision ledger.
Inputs: outcome (required), request_id (required), session_id (required), project_key (required), +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools map to distinct operations: pray triggers the recovery ritual, report_outcome writes/advances the ledger, and inspect_ledger is explicitly read-only and non-advancing. The write-vs-read distinction between report_outcome and inspect_ledger is spelled out, leaving little overlap, though pray's sprawling trigger criteria make its boundary with normal debugging judgment a bit fuzzy.
report_outcome and inspect_ledger follow a clean verb_noun pattern, and pray is a single bare verb that fits the idiom of this ritual-themed server. Minor deviation from strict consistency, but readable and predictable.
Three tools is a tight but defensible surface for a narrow recovery-loop domain (trigger, record, inspect). It is on the thin side, but each tool clearly earns its place rather than being padding.
The core loop of initiate, record, and inspect is present, but lifecycle gaps remain: no way to reset/close a session, clear or initialize a ledger, or enumerate past sessions. An agent can work within the loop but hits dead ends outside it.
Maintenance
Related MCP Connectors
Stops runaway AI agent loops and token burn. Checks each tool call before it runs. No signup.
Watchdog for unattended AI agents: alerts, evidence checks and a verifiable proof per run.
Enforces architectural invariants and code quality rules inside your AI agent's edit loop.
Checks AI-written code for leaked keys and made-up packages, on your machine. Never uploads code.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI coding agents to avoid irreversible mistakes by intercepting risky deletions, overwrites, and commands before execution, applying path, pattern, and blast-radius safeguards with quarantine backups.39 npmMIT
- AlicenseAqualityBmaintenanceZero-dependency token optimizer, test-failure triage gate, and System 1.5 semantic guardrail for AI coding agents. Intercepts compiler errors, missing dependencies, and doom loops in < 500µs.612MIT
- AlicenseNot gradedqualityBmaintenanceA universal interceptor that sits between any AI model's tool calls and shell execution, routing them through a supervisor daemon that inspects AST deltas, subprocess output, and hash-chained ledgers before work is allowed. It enables users to kill deleted assertions, trivial stubs, phantom test runs, and cyclic self-debate loops deterministically at the compiler, process, and filesystem boundaries rather than via prompt instructions.AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to control real interactive shells, REPLs, and TUIs over stdio, supervise other agents, surface approval prompts, and verify outcomes without auto-approving or mistaking timeouts for success.1MIT