WhyStuck
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
WhyStuck
Diagnose the loop. Propose the fix. You approve.
Works with
Local-only · No telemetry
Install · How it works · Why not X? · Status · Roadmap · Docs · Discuss
Your coding agent re-ran
npm install40 times and you didn't notice. WhyStuck records why a repeated agent loop keeps failing, shows you the failure mode with a confidence level, and proposes a small, reversible patch — to the verifier, retry policy, stop condition, or skill — that you approve before anything is written.
WhyStuck is the diagnosis-and-repair layer for loop engineering.
2026's agent-dev stack goes prompt → context → harness → loop engineering: you
stop prompting the agent turn-by-turn and design the act→verify→retry→stop cycle
that drives it (ADTmag).
Loop scaffolders help you build a loop; WhyStuck tells you why it keeps failing
and what to change. Every named alternative — Latitude, LangSmith, Braintrust,
Langfuse — is cloud SaaS for production apps; none does local, zero-telemetry,
coding-agent-session loop diagnosis. WhyStuck's reflective-mutation approach
builds on GEPA (Genetic-Pareto, ICLR 2026
Oral); the measured GEPA optimization itself arrives in
v0.2, which wraps gepa-ai/gepa.
The diagnosis is deterministic — it spends ~0 model tokens; only the proposed fix uses your agent's own model. No API key to diagnose, nothing uploaded, and it stays out of your request hot path.
Install
Requires
uv. Ifuvxisn't found:curl -LsSf https://astral.sh/uv/install.sh | sh
One command — configures Claude Code, Codex, and Cursor:
uvx whystuck setupThe wizard writes each client's MCP config and a short usage rule — so your
agent knows to diagnose a stuck loop before it thrashes — merges into any
existing config, and is safe to re-run. Choose clients/scope with
--all · --claude · --cursor · --codex · --global · --yes.
It registers WhyStuck as a local stdio MCP server (no pip install, no venv) and
stores traces under $XDG_DATA_HOME/whystuck — outside your repo, never
committed by accident.
claude mcp add whystuck -- uvx whystuck # Claude Code
codex mcp add whystuck -- uvx whystuck # Codex CLICursor / any MCP client — add to your mcp.json:
{ "mcpServers": { "whystuck": { "command": "uvx", "args": ["whystuck"] } } }Then paste one line into AGENTS.md / CLAUDE.md / .cursor/rules so the agent
reaches for it automatically (the wizard does this for you). See AGENTS.md.
Pre-launch:
whystuckisn't on PyPI yet, souvx …won't resolve. Run the wizard from a clone instead:git clone https://github.com/loopgepa/whystuck && cd whystuck uv run whystuck setup --from-source "$PWD"
git clone https://github.com/loopgepa/whystuck && cd whystuck
uv run python examples/bugfix-loop/demo.pyPrints the full flow: 8 traces → "repair repeats the original patch" (confidence:
medium, gene: verifier_rubric) → proposed variant → dry-run promotion.
Related MCP server: SentinelMCP
How it works
declare loop ─▶ run it (worker + verifier) ─▶ clean local trace (JSONL)
│
failure diagnosis ◀── aggregate ◀───────┘ (deterministic + confidence)
│
reflective fix (≤3 genes, evidence-backed) ─▶ dry-run diff ─▶ you approve ─▶ reversible promoteDeclare a loop — its genome of genes (skill, verifier rubric, retry policy, stop condition, …).
Run / record it: the offline command+verifier runner emits a clean trace, or your agent records session traces.
Diagnose: failures are clustered and ranked with a deterministic confidence (
n<5→low,≥15 ∧ cluster≥0.5→high) — no LLM in the analysis.Propose: your agent reflects on the evidence and proposes a ≤3-gene patch.
Preview the exact diffs (dry-run writes nothing), then approve — the write is atomic and reversible, with a rollback record.
WhyStuck runs the loop, so every knob it tunes is real, and every trace is clean by construction — and it never writes without your approval.
Why not just X?
WhyStuck | Latitude / LangSmith / Braintrust / Langfuse | |
Runs | On your machine | Cloud SaaS |
Data | Never leaves it, no telemetry | Uploaded to a backend |
Scope | Your local coding-agent loops | Production LLM apps |
Output | A reversible patch you approve | Dashboards / auto-PRs |
Nobody else pairs local + zero-telemetry + coding-agent-session scope + reversible, approval-gated repair. Fuller breakdown: docs/comparison.md.
Status
Developed in the open once solid; the trust chain and diagnosis pipeline are built and tested.
Component | State |
Loop genome + local store (XDG) | ✅ |
Command+verifier runner (offline) | ✅ |
Deterministic diagnosis + confidence | ✅ |
Reflective mutation (≤3 genes, safety-guarded) | ✅ |
Dry-run + reversible promotion + rollback | ✅ |
FastMCP stdio server (6 tools) | ✅ |
Claude Code plugin (3 skills, 3 agents) | ✅ |
Auto-trigger hook (thrash detection + session capture) | ✅ |
Evaluation library + GEPA wrapper ( | 🟡 v0.2-alpha |
LLM worker + output→apply→verify wiring (real-repo scoring) | 🟡 v0.2-alpha |
Optimize + frontier MCP tools (gated on the extra) | 🟡 v0.2-alpha |
2755 tests, all local and offline; ruff + mypy --strict (on src/) + docs --strict clean.
Configure
The server is zero-config. Point any MCP client at it:
{ "mcpServers": { "whystuck": { "command": "uvx", "args": ["whystuck"] } } }Storage location is overridable with WHYSTUCK_HOME (default
$XDG_DATA_HOME/whystuck). No API keys — the v0.1 runner is fully offline.
MCP tools & safety boundary
Six focused tools: diagnose, run_loop, propose_fix, promote, save_loop,
and the internal record_trace. The boundary is mechanical: promote is
dry-run by default and only writes on an explicit approval flag; proposals are
capped at 3 genes; budget caps can't be weakened; promotion paths can't escape
the project directory. Full threat model: SECURITY.md.
Roadmap
See ROADMAP.md.
✅ v0.1 — diagnose recurring loop failures, propose reversible fixes; a PostToolUse hook auto-detects thrash and captures session traces
🟡 v0.2-alpha — eval library + GEPA wrapper + LLM-backed worker built (
whystuck[eval], gated MCP tools); remaining: the output→apply→verify wiring for real repos + the benchmark writeup📋 v0.3 — plugin marketplace listing (manifest ready), MCP-registry submission
Research artifact
This repository is the supporting artifact for a three-paper series on optimizing generate–critique–refine loops. Start at docs/papers/README.md — it says which paper answers which question.
paper | in one line | |
I | Evolving a Self-Refine Verifier: It Stops Accepting at a Low Base Rate, and Whether That Pays Remains Open | On one worker, evolving a loop's verifier does not measurably beat evolving its generation prompt at p₀ = 0.067, the base rate of already-correct first drafts, where the search stops the verifier accepting. Paper I reports a single cell at p₀ = 0.267 (+0.060 held-out, three seeds) inside the spread of the low-p₀ runs and has withdrawn its claim that the answer tracks p₀ |
II | What a Checker Cannot Buy Is the Repair | Where few first drafts pass (p₀ = 0.067), at one refine round, a perfect checker that names the failed constraints buys nothing measurable over a near-random self-critique and scores 0.042 below a text-statistics tool, on thirty fixed tasks. Holding it perfect, naming the constraint with a measured repair edit is worth +0.0613 over a bare verdict. Every number it measures scores a fixed genome; two optimizer contrasts are quoted from the companions |
III | A Loop Optimizer That Was Not Optimizing Its Loop | Pointing an optimizer at a component is not the same as optimizing it. Replayed, ten of the twelve replayable runs among our first fifteen had a critique gene byte-identical to the seed in every winning genome, and the other two moved it on one seed each; only five of the twelve could have shown a move. Print one integer per component |
Every experiment, and the command that produced it — one script spends money and it refuses to without
--yes; everything else is $0 and offline.How to reproduce it — offline checks, all $0: every number in every paper re-derived from the artifacts, bit-for-bit cassette replay, a positive control proving the harness detects an effect when one exists, and a proof that the three-way split lost no claim.
Results, cassettes and pre-registrations for every run are committed, including the superseded ones, labelled as such.
Documentation
The three papers — which paper answers which question
Every experiment and its command — the map from a claim to a script
How it works — loop engineering, the genome, the pipeline
Where to find WhyStuck
Channel | Install | Notes |
PyPI |
| primary; zero-install via |
MCP registry | auto-discovered | via |
GitHub |
| source + examples |
Contributing
Highest-impact area right now: real loop examples beyond the bugfix loop
(an orchestrator/triage loop). See CONTRIBUTING.md and the
good first issue label.
License
Apache-2.0 for the code — see LICENSE.
The papers under docs/papers/ are licensed CC BY 4.0 instead — see
docs/papers/shared/LICENSE. Two separate grants: a patent grant and NOTICE
requirement make no sense for a document, and the papers are meant to be redistributed and
built upon. CC BY 4.0 is also the licence selected for the arXiv submissions.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Diagnose why an AI agent failed and get the verified fix instantly. Free, no token.
Scores an AI agent's execution trace 0-100 and returns concrete fixes. Free, no API key.
1Finds what's broken in your product, explains why, and fixes it from your agent.
Recovery loop for agent tool catalogs: measured confusion, ranked fixes, signed recovery receipts.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables LLMs to automatically diagnose coding errors through codebase search, test execution, and live debugger integration (DAP/V8 CDP). Provides a secure, policy-gated environment for investigating failures while preventing destructive operations.9ISC
- FlicenseAqualityDmaintenanceEnables LLM-driven agents to autonomously detect, diagnose, repair, verify, and prevent software and hardware failures on local and remote systems. Includes built-in safety checks and automatic rollbacks.15-
- AlicenseAqualityCmaintenanceProvides AI coding agents with reliable root-cause diagnosis and minimal, high-confidence fixes for failing tests.31MIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to capture and replay intermittent software failures, minimize reproductions, compare trials, search regressions, verify proposed fixes against a saved failing baseline, and retrieve investigation evidence without rerunning commands.52 npmMIT