ctrl-alt-pray

v2.0.0

Published

13 days ago

**When Ctrl+Z isn't enough.**

0High
0Medium
0Low

mcp model-context-protocol ai-agent cursor claude-code debugging circuit-breaker anti-hallucination developer-tools terminal-guardian

🕯️ Ctrl Alt Pray

When Ctrl+Z isn't enough. Pray.

The open-source anti-doom-loop circuit breaker & epistemic supervisor for Cursor, Claude Code, Cline, and autonomous AI agents.
Halt circular edits. Terminate zombie terminals. Force your AI to find the ground truth.

       🕯️  THE ALTAR OF GROUND TRUTH HAS BEEN SUMMONED  🕯️
       [ PRAYERS ARE OPTIONAL. FALSIFIABLE EVIDENCE IS REQUIRED. ]

⭐ Star on GitHub • Quickstart in 10s • Before vs After • Core Superpowers • The 12 Canonical Rites • CLI Cheat Sheet

💀 The 3:00 AM Agony: Before vs After

Every software engineer working with autonomous coding agents knows this visceral frustration:

| ❌ Without ctrl-alt-pray | ✅ With ctrl-alt-pray | | :--- | :--- | | Attempt 1: AI edits line 42. Test fails. | Attempt 1: AI edits line 42. Test fails. | | Attempt 2: "I apologize for the confusion! Let me fix that!" AI edits line 42 again. Test fails. | Attempt 2: AI tries again and fails. CIRCUIT BREAKER TRIPS. | | Attempt 3: AI edits line 43. Reverts line 42. Still fails. | 🛑 In-Context Tripwire: AI is strictly forbidden from writing code without new discriminating evidence. | | Attempt 5: Terminal hangs for 20 minutes because a dev command was waiting on an unhandled (y/n)? prompt. | ⚡ Active Guardian (pray-run): Detects silence >15s, executes Cascade Tree Kill on orphaned child processes, and frees occupied dev ports. | | Attempt 8: 14 dirty files churned. Hallucinated function exports stacked. Context window saturated. | 🌾 Universal Harvester: Checks git & ports automatically: "You edited src/ but tests execute stale dist/." | | Attempt 14: AI apologizes for the 10th time, burns another 50k tokens re-explaining the same false premise. | 🔥 Heresy Mode: Slaps the AI with an iconoclastic falsification probe, resetting hypothesis space to ground reality. | | Result: $28 in API tokens burned. Dirty git working tree. 2 hours lost. Bug still broken. | Result: Subsystem isolated in 30 seconds. Baseline restored. $0.02 spent. |

The Empirical Law of AI Coding Loops:
If an AI agent fails twice consecutively on the same defect, attempting a third speculative patch with the same assumptions has a <4% success rate. Without an external circuit breaker, it will apologize profusely, hallucinate alternate APIs, and burn your context window.

⚡ Quickstart (10 Seconds)

Step 1: Arm any repository

Run this single ignition command in the root of your project:

npx ctrl-alt-pray init

ctrl-alt-pray automatically detects your active development environment and equips it with the non-negotiable 2-Strikes Circuit Breaker:

Cursor: Injects tripwire into .cursorrules and provisions .vscode/mcp.json.
Claude Code: Injects into CLAUDE.md.
Google Antigravity / Gemini CLI: Injects into GEMINI.md.
Cline / Roo Code: Injects into .clinerules.
OpenCode: Registers MCP in opencode.jsonc.
Universal Fallback: Creates standard AGENTS.md recognized by modern coding agents.

Step 2: Code with peace of mind

Work as you always do. But the instant your AI fails twice on the same check, the tripwire forces it to summon the Altar of Ground Truth (pray) instead of guessing.

🏛️ The 4-Tier Trigger Architecture

Autonomous agents trapped in doom loops suffer from cognitive tunnel vision—they lack the meta-cognition to declare "I am stuck". ctrl-alt-pray operates an active 4-tier hierarchy to intercept failures:

┌─────────────────────────────────────────────────────────────────────────────┐
│                    4-TIER ANTI-DOOM-LOOP ARCHITECTURE                       │
├─────────────────────────────────────────────────────────────────────────────┤
│ Tier 1: Passive Schema Reflex    │ Tool schema enumerates exact symptoms    │
│ (Zero-Config Attention Bias)     │ (consecutive fails >= 2, freeze > 15s)   │
├──────────────────────────────────┼──────────────────────────────────────────┤
│ Tier 2: In-Context Tripwires     │ npx ctrl-alt-pray init generates         │
│ (System Prompt Enforcers)        │ mandatory 2-strikes circuit breaker rule │
├──────────────────────────────────┼──────────────────────────────────────────┤
│ Tier 3: Active Terminal Guardian │ pray-run wrapper detects silent freezes  │
│ (Synthetic Stream Injection)     │ & terminates zombie child process trees  │
├──────────────────────────────────┼──────────────────────────────────────────┤
│ Tier 4: The Altar & Harvester    │ Universal harvester reads git, ports,    │
│ (Autonomous Ground-Truth Engine) │ & test archaeology to prescribe probes   │
└──────────────────────────────────┴──────────────────────────────────────────┘

🚀 Core Superpowers

1. 🛑 The Injected Tripwire (The 2-Strikes Rule)

When npx ctrl-alt-pray init runs, it embeds an ironclad behavioral contract:

<!-- START CTRL-ALT-PRAY TRIPWIRE -->
### 🛑 Anti-Doom-Loop Circuit Breaker (ctrl-alt-pray)
1. STRICT 2-FAILURE LIMIT: If ANY test, build, or command fails twice with the same error, STOP editing immediately.
2. NO BLIND GUESSING: Do not touch application code a 3rd time without verified new evidence.
3. MANDATORY ACTION: Invoke MCP tool 'pray'. It will freeze speculative edits and prescribe ONE bounded falsification experiment.
4. TERMINAL FREEZE: If a command hangs >15s with zero output, kill it and invoke 'pray' (strategy="ghost-terminal-breaker").
5. ZERO APOLOGIES: Do not apologize. State your single testable hypothesis and execute the probe.
<!-- END CTRL-ALT-PRAY TRIPWIRE -->

2. ⚡ Active Terminal Guardian (`pray-run`)

Tired of watching your AI run npm test or vite and freeze for 20 minutes because a process is waiting on an invisible (y/n)? prompt, background watcher, or locked database?

Prefix your commands with pray-run:

pray-run pnpm test
# or
pray-run npm run build

╔═════════════════════════════════════════════════════════════════════════════════╗
║          [CTRL-ALT-PRAY GUARDIAN] TERMINAL HANG DETECTED (>15s silent)          ║
╠═════════════════════════════════════════════════════════════════════════════════╣
║ Process and all descendant child processes terminated via Cascade Killer.       ║
║ Probable cause: Subprocess pipe deadlock, forgotten watcher, or prompt (y/n)?   ║
║                                                                                 ║
║ ACTION REQUIRED: Invoke MCP tool 'pray' with strategy='ghost-terminal-breaker'  ║
╚═════════════════════════════════════════════════════════════════════════════════╝

15-Second Freeze Watchdog: Spawns child commands under real-time stdout/stderr supervision.
Cascade Process-Tree Killer: Recursively terminates the entire process subtree (orphaned node, vitest, esbuild workers adopted by PID 1), guaranteeing dev ports (:3000, :5173) and .git/index.lock are released.
Flapping Exit Code Breaker: Tracks consecutive failures across runs in .ctrl-alt-pray/runs.json. If identical non-zero exit codes repeat 3 times, Guardian displays an unmissable terminal circuit breaker.

3. 🌾 Universal Zero-Argument Harvester (`pray()`)

When an agent is panicking, demanding that it construct a 60-line JSON payload with candidate_hypotheses, observations, and constraints only induces secondary hallucinations.

With ctrl-alt-pray, the AI can call pray with zero arguments:

{}

The Universal Harvester automatically inspects runtime reality:

Git Sepsis & Flapping: Scans git status --porcelain and diffs. If $\ge 4$ files are dirty, flags clean-slate-rollback. If a file is repeatedly edited and reverted, locks edit permissions.
Socket Contention: Uses native node:net to probe standard dev ports (3000, 4321, 5173, 8080, 9222) across macOS, Linux, and Windows for stale background daemons.
Pluggable AI Archaeology: Reads test artifacts (.vitest/, .pytest_cache/, test-results/) and local client configs (.cursor/, CLAUDE.md, GEMINI.md, .aider.chat.history.md).

4. 🔥 Heresy Mode & The Offering

When an agent fixates on a false premise ("The database query must be wrong!" when the server is actually executing a stale build artifact):

Heresy Mode (heresy_mode: true): Tripped automatically on attempt 3. Challenges the foundational premise and provides a cheap, decisive falsification check:
- Wrong Altar: Inject an intentional syntax error in source. If tests still pass, your source file is not being compiled.
- Phantom Module: Run node -e "import('<mod>').then(m => console.log(Object.keys(m)))" to inspect true runtime exports instead of guessing method names.
- Poison Chalice: Inject assert.strictEqual(1, 2) into the business logic. If tests stay green, your test suite is swallowing errors.
The Offering (session.offering): When the problem cannot be resolved by more code, the Altar demands missing evidence:
- minimal_input: A stripped-down JSON payload with $<5$ fields isolating the bug.
- product_decision: A multiple-choice business rule decision for the human owner.
- known_good_comparison: A side-by-side trace of working vs broken environments.

5. ⚰️ Clean-Context Resurrection (`pray resurrect`)

When an agent's context window is poisoned with 30 turns of failed speculative reasoning, continuing in the same session is a waste of money.

Run:

ctrl-alt-pray resurrect [session_id]

Or query MCP resource session://{session_id}/resurrection:

The engine outputs a compact Markdown Resurrection Packet:

The Core Goal & Constraints: Inviolable boundaries.
Verified Ground Truth: Hard facts proven by command exit codes and passing assertions.
Ruled-Out Hypotheses (DO NOT RECYCLE): Approaches already attempted that failed—forbids the fresh agent from repeating them.
Active Bounded Probe: Exactly ONE isolated check with clean rollback.
Zero Speculative Narratives: Wipes away the prior agent's excuses and hallucinations.

6. 📜 The Prayer Book: 12 Canonical Rites (`pray recipes`)

Need to browse battle-tested recovery patterns? Run:

ctrl-alt-pray recipes
# or
ctrl-alt-pray book

All 12 canonical recipes are version-controlled with applicability triggers, probes, outcome branches, and safety guarantees.

7. ⚖️ Second Opinion & Devil's Advocate (`second_opinion: true`)

When an agent or developer wants to challenge their recovery plan before touching code:

Adversarial Critique: Challenges the proposed experiment to expose hidden assumptions, non-deterministic flakiness, or uncalled mocks.
MCP 2026 Sampling Protocol: If the host MCP client advertises sampling (sampling: {}), requests an independent Devil's Advocate critique via sampling/createMessage with strict resource bounds (<150 tokens, 4s timeout).
Zero-Cost Heuristic Fallback: Gracefully degrades to a fast, 0-token heuristic critique if sampling is unsupported or unconfigured.

🏛️ The 12 Canonical Recovery Recipes

📊 Visual Ledger & Telemetry Dashboard

Live Web Dashboard (`http://127.0.0.1:3900`)

Launch the Apple/Linear minimalist recovery ledger with one command:

ctrl-alt-pray dashboard

Live UI: Dark slate palette (#090d16), 100% SVG vector iconography, zero bloat.
Offline HTML Report: Automatically exports a standalone, portable report to ~/.ctrl-alt-pray/dashboard.html.
Session Inspector Modal: Click any session to inspect exact handoff notes, verified observations, and rejected hypotheses.

CLI Telemetry (`pray stats`)

For a quick terminal audit of intercepted loops and saved tokens:

pray stats

  ┌──────────────────────────────────────────────────────────┐
  │                   CTRL ALT PRAY TELEMETRY                │
  │            "When Ctrl+Z isn't enough. Pray."             │
  └──────────────────────────────────────────────────────────┘

  Active Sessions Recorded:  23
  Loops Intercepted:         20
  Loop Recovery Rate:        87.0%
  Estimated Tokens Saved:    ~195,500 tokens (~$2.93)

  TOP FAILURE MODES INTERCEPTED:
  • Ghost Terminal Deadlocks:    38%  ████████████
  • API / Symbol Hallucinations: 26%  ████████
  • Code Sepsis (Dirty Churn):   21%  ███████
  • Wrong Altar (Stale Builds):  15%  █████

  Storage: SQLite WAL (~/.ctrl-alt-pray/sessions.sqlite)

The Confessional (`pray history`)

Replay the exact 3-step decision tree that resolved an agent's stuck state:

pray history [session_id]

🧙‍♂️ Occult Easter Eggs: "The Altar Scowls"

Behind the candles and Latin rites lies uncompromising engineering discipline:

1. The Anti-Apology Scowl

When an agent enters cognitive panic, its output degenerates into placating filler ("I apologize for the confusion! Let me correct...").

The Altar slaps it back to reality:

🕯️ [THE ALTAR SCOWLS]
The Gods accept no apologies from mortals. Apologies do not pass test suites.
State your single falsifiable hypothesis and execute the probe.

2. Divine Favor (Karma RNG Roll)

Inside the AI's hidden reasoning context, it receives an epistemic karma roll (1–100):

< 40: Dire Wrath (Altar Scorn - Apologies Detected)
< 60: Trial of Patience (Temperate Grace)
< 80: Auspicious Omen (Fortunate Insight)
$\ge 80$: Transcendent Grace (Divine Favor)

<thinking>
- Test failed twice on stale import. Tripping circuit breaker...
- Calling MCP tool 'pray'...
- Received Rite: 🏛️ [EXPOSING THE FALSE IDOL]
- Divine Favor Roll: 96/100 (Transcendent Grace — Divine Favor).
- Handoff: "The build artifact is stale; kindle the fire of fresh compilation."
- Action: Purging dist/ and rebuilding before modifying source code.
</thinking>

💎 Why Developers Star This

Zero External Runtime Dependencies: Built strictly using Node 22+ native standard modules (node:sqlite, node:net, node:fs, node:child_process) and @modelcontextprotocol/server. No native C++ bindings, no node-gyp, no bundle bloat.
Dual-Driver Storage Resilience: Primary persistence runs on high-performance native node:sqlite in WAL mode (~/.ctrl-alt-pray/sessions.sqlite). Automatically falls back to atomic JSON file storage (sessions.json via write-and-rename) if SQLite is restricted.
Zero Remote Telemetry: 100% local. Your code, diffs, stack traces, and prompts never leave your local machine.
Automatic Secret Scrubbing: Regex-scrubs GitHub tokens (ghp_), OpenAI/Anthropic keys (sk-), AWS credentials (AKIA), and Bearer headers before persisting any record.
Sub-10ms Cold Start: Instant ignition across CLI and MCP stdio transports.

📟 CLI Cheat Sheet

# 1. Arm any repository with the 2-Strikes circuit breaker
npx ctrl-alt-pray init

# 2. Run test/build commands with 15s freeze watchdog & zombie cleanup
pray-run npm test

# 3. View telemetry on intercepted loops and saved tokens
pray stats

# 4. Browse the 12 canonical recovery recipes
ctrl-alt-pray recipes

# 5. Export clean resurrection packet for fresh context restart
ctrl-alt-pray resurrect [session_id]

# 6. Replay the recovery timeline of a session
ctrl-alt-pray history [session_id]

# 7. Launch local visual dashboard
ctrl-alt-pray dashboard

# 8. Administrative purge of old sessions (>7 days)
ctrl-alt-pray purge

🛠️ Manual MCP Setup

If you prefer to configure your MCP client manually without npx ctrl-alt-pray init:

Cursor (`.cursor/mcp.json` or `.vscode/mcp.json`)

{
  "mcpServers": {
    "ctrl-alt-pray": {
      "command": "npx",
      "args": ["-y", "ctrl-alt-pray"]
    }
  }
}

Claude Code (`~/.claude.json`)

{
  "mcpServers": {
    "ctrl-alt-pray": {
      "command": "npx",
      "args": ["-y", "ctrl-alt-pray"]
    }
  }
}

Google Antigravity / Gemini CLI (`mcp_config.json`)

{
  "mcpServers": {
    "ctrl-alt-pray": {
      "command": "npx",
      "args": ["-y", "ctrl-alt-pray"]
    }
  }
}

🤝 Contributing

Contributions are welcome! Whether you are adding a new canonical recovery rite, expanding harvester client adapters, or improving freeze detection heuristics:

Clone the repo: git clone https://github.com/HoangYell/ctrl-alt-pray.git
Install dependencies: pnpm install
Run tests: pnpm test (100% pass required)
Run evaluation benchmark: pnpm eval
Open a Pull Request!

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme