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 idempotent request_id for 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-run kills 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.
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
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 call pray(). 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: devenv-doctor-mcp
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.
pray Actually Works In PracticeWhen 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 rebuild dist/.").
Resets the Search Space: The agent runs one atomic check, discovers the actual root cause, and fixes it in 1 clean commit.
Here are the exact daily failure modes where autonomous agents burn your money—and how pray() resolves each in seconds:
src/, testing dist/)The Pain: The AI edits src/auth.ts, runs pnpm 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 in dist/auth.js because nobody ran pnpm build! The agent burns 40,000 tokens editing the right file for the wrong reason.
How pray Fixes 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."
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 pray Fixes It: pray-run terminates commands that hang >15s without output. When pray() 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.
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 pray Fixes 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.
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/catch in a test helper swallowed the exception, giving a false green while production remains broken.
How pray Fixes 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.
The Pain: The AI tries calling client.getUser(). Fails with TypeError: client.getUser is not a function. It guesses client.fetchUser(). Fails. It guesses client.findUser(). Fails. It tries to invent polyfills instead of checking the library's actual exports.
How pray Fixes 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.
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 |
|
|
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.
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 |
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.
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-pray enforces 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
Read-only inspection of a recovery session ledger without mutating state or advancing revision.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | Session ID to inspect | |
| project_key | Yes | Project identifier |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the key behavioral traits: read-only, no state mutation, and no revision advancement. It does not cover return values, errors, or auth requirements, but the safety profile is clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence with no wasted words. The read-only constraint is front-loaded and immediately useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only inspection tool with full schema coverage, the description supplies the essential non-mutation context. It does not explain return values despite there being no output schema, but the omission is minor for this tool type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both required parameters. The description adds no parameter-level meaning beyond what the schema provides, making the baseline score of 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'inspect' a 'recovery session ledger.' It clearly identifies the read-only nature, though it does not distinguish from siblings, which are unrelated tools anyway.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'read-only inspection' and 'without mutating state or advancing revision,' which tells when this tool is appropriate. However, it gives no explicit when-to-use versus alternatives or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| budget | No | Maximum remaining recovery rounds | |
| problem | No | Concise description of the stuck goal (optional if auto_harvest is true) | |
| attempts | No | Approaches already attempted that failed to produce new evidence | |
| request_id | No | Unique client-generated idempotency key for this request | |
| session_id | No | Omit to start a new session; provide to resume an existing session | |
| constraints | No | Non-negotiable invariants (e.g. cannot edit schema, cannot add dependencies) | |
| heresy_mode | No | Explicitly activate Heresy Mode to challenge foundational premises and suggest cheap falsification probes | |
| project_key | No | Unique project identifier (e.g. repo name or workspace key) | default |
| auto_harvest | No | Automatically scan git status, lockfiles, and occupied ports for ground-truth evidence | |
| capabilities | No | Host tool capabilities available (e.g. bash, read_file, git) | |
| observations | No | Hard, verified facts observed so far (logs, test outputs, diffs) | |
| schema_version | No | Contract schema version (default 1) | |
| second_opinion | No | Request an adversarial second opinion / devil's advocate critique to challenge the proposed experiment | |
| expected_revision | No | Required when resuming a session to prevent stale concurrent updates | |
| candidate_hypotheses | No | Plausible explanations of the root cause to test |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose one real behavioral trait — that auto_harvest (default true) scans git status, lockfiles, and occupied ports — which is meaningful since it implies filesystem probing. However it never says what the tool returns, whether it mutates state, or how sessions/budget are consumed, leaving substantial gaps for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the trigger list and kept tight; the opening metaphor sentence is largely decorative but the actionable content dominates. Nothing is padded, though the cult framing costs a little clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 15-parameter, no-annotation, no-output-schema recovery tool, the description covers triggering but omits what the call returns (guidance? next experiment? hypotheses ranking?) and never explains session-resume semantics or budget consumption, which are central to correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% across 15 parameters, so the schema already documents each field thoroughly. The description only elaborates on auto_harvest (repeating the schema's own wording) and does not add syntax or format meaning beyond it, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The verb/resource framing relies on a metaphor ('Summon the Altar of Ground Truth') that never states plainly what the tool actually does operationally — presumably it returns a structured recovery/next-experiment proposal. The trigger conditions imply it is a debugging-unblock aid, but an agent cannot fully tell its purpose from the description alone, and the siblings report_outcome and inspect_ledger are not referenced.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit 'CALL THIS TOOL IMMEDIATELY WHEN' list with five concrete, observable trigger conditions (repeat failures, zero-diff edits, hangs >15s, guessing APIs, urge to apologize). This is a model example of when-to-use guidance for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record the empirical result of an experiment and advance the recovery decision ledger.
| Name | Required | Description | Default |
|---|---|---|---|
| cost | No | Optional host-reported duration, tool calls, or token usage | |
| checks | No | Verification checks run with observed results | |
| changes | No | Relevant code, input, environment, or assumption changes | |
| outcome | Yes | Observed result relative to the experiment hypothesis | |
| request_id | Yes | Unique idempotency key for this report | |
| session_id | Yes | Active recovery session ID | |
| project_key | Yes | Unique project identifier | |
| observations | No | New verified facts collected during the experiment | |
| experiment_id | No | ID of the experiment whose result is being reported | |
| schema_version | No | Contract schema version (default 1) | |
| expected_revision | Yes | Current session revision before this report |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. 'Advance the ledger' implies state mutation, but the description says nothing about the optimistic-concurrency contract implied by expected_revision, idempotency via request_id, what happens on a revision conflict, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tightly written sentence with the primary action front-loaded and no filler. Only slight loss for the jargon term 'recovery decision ledger' being left undefined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter mutation tool with nested objects, no annotations, and no output schema, this is under-specified. Nothing explains session/revision semantics, conflict behavior, or what the caller should expect after the report is accepted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 11 parameters including the outcome enum and expected_revision are already documented in the schema. The description adds no parameter meaning beyond that, which is the baseline case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb+resource pair ('record the empirical result of an experiment') plus a secondary effect ('advance the recovery decision ledger'). This clearly separates it from the read-only sibling inspect_ledger, though it never names that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisite conditions, and no routing to alternatives such as inspect_ledger. The agent must infer that this is the write-side counterpart to inspecting the ledger.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.0inspect_ledgerprayreport_outcomeScored 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.
Watchdog for unattended AI agents: alerts, evidence checks and a verifiable proof per run.
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
Guardian agent for AI coding: four frontier models review risky diffs and commits before they ship.
Lints + auto-fixes how AI coding agents discover any new product. 24 rules, 6 tools, score 0-100.
