Skip to main content
Glama

WhyStuck

Diagnose the loop. Propose the fix. You approve.

CI License: Apache-2.0 PyPI Stars Discussions

Works with   Claude Code   Codex CLI   Cursor   Local-only · No telemetry

Install · How it works · Why not X? · Status · Roadmap · Docs · Discuss

Your coding agent re-ran npm install 40 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. If uvx isn't found: curl -LsSf https://astral.sh/uv/install.sh | sh

One command — configures Claude Code, Codex, and Cursor:

uvx whystuck setup

The 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 CLI

Cursor / 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: whystuck isn't on PyPI yet, so uvx … 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.py

Prints 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 promote
  1. Declare a loop — its genome of genes (skill, verifier rubric, retry policy, stop condition, …).

  2. Run / record it: the offline command+verifier runner emits a clean trace, or your agent records session traces.

  3. Diagnose: failures are clustered and ranked with a deterministic confidence (n<5→low, ≥15 ∧ cluster≥0.5→high) — no LLM in the analysis.

  4. Propose: your agent reflects on the evidence and proposes a ≤3-gene patch.

  5. 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 (whystuck[eval])

🟡 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

Where to find WhyStuck

Channel

Install

Notes

PyPI

uvx whystuck

primary; zero-install via uv

MCP registry

auto-discovered

via server.json (feeds mcp.directory, Glama)

GitHub

git clone

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

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      9
      ISC
    • F
      license
      A
      quality
      D
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT