LoopLens MCP 🔁🔍

See the loop. Break the loop.

LoopLens MCP is an iteration observability and loop-detection MCP server for Claude Code and agentic coding workflows.

It is built for a very specific pain point:

You ask the model to fix something. It tries. The fix fails. You ask again. It retries. Same issue. More edits. More noise. 😵‍💫

LoopLens turns that messy retry cycle into structured debugging intelligence.

✨ What is LoopLens MCP?

LoopLens is not a memory MCP. LoopLens is not just another logger.

It is a focused debugging intelligence layer that helps AI coding workflows understand:

• what has already been tried 🔁

• what changed between attempts 🧩

• which failures keep repeating 🚨

• whether the workflow is converging or thrashing 📉📈

• what the next most promising debugging step should be 🎯

Related MCP server: trw-mcp

🤔 Why LoopLens exists

AI coding tools can be amazing on first-pass fixes.

But repeated repair attempts often become chaotic:

• same failing command again and again

• same files edited repeatedly

• same tests still red

• new wording, same failure

• regressions introduced while fixing something else

• retries that look different but are actually the same loop

That is exactly where LoopLens helps.

🧠 Core capabilities

1. Iteration logging

Capture repair/debug attempts across a task.

2. Attempt linking

Detect whether a prompt is:

• a new task

• a continuation

• a retry

• a regression check

• a strategy branch

3. Loop detection

Identify patterns such as:

• identical retry loops

• repeated error signatures

• command retry loops

• file oscillation

• validation stagnation

• evidence-free retries

• regression after partial success

4. Attempt comparison

Compare attempt N vs N-1:

• files changed

• tools used

• commands run

• validations changed

• hypothesis shifts

• outcome shifts

5. Convergence analysis

Estimate whether the workflow is:

• converging ✅

• weakly converging 🤏

• stagnant 😐

• diverging 📉

• regressing ⚠️

6. Next-fix suggestions

Recommend the best next move:

• gather more evidence

• isolate root cause

• narrow validation

• revert harmful change

• inspect external signals

• stop editing and compare attempts

• split task into subproblems

7. Connector observations

LoopLens can ingest signal from:

• GitHub / GitLab

• CI systems

• Sentry

• Jira / Linear

• test runners

• filesystem metadata

• other MCP servers

LoopLens is the debugging brain 🧠 Other tools are signal sources 📡

💡 Philosophy

Don't just log the attempt. Understand the iteration.

That means:

• structured trajectories instead of flat logs

• failure fingerprints instead of noisy raw output

• loop diagnosis instead of generic analytics

• actionable next-step guidance instead of passive storage

🚫 Not a memory MCP

LoopLens does not try to become long-term user memory.

It focuses on:

• observable debugging events

• tool calls

• validation results

• explicit summaries

• failure patterns

• retry trajectories

It is built for debugging, evaluation, and improvement of coding workflows.

🛠 Example use cases

• "Why did the last 3 fixes fail?"

• "Are we editing the same files without real progress?"

• "Did the failure actually change?"

• "Are we stuck in a retry loop?"

• "Which attempt got us closest to success?"

• "What should Claude try next?"

• "Export the last 20 failed repair loops as eval cases."

🚀 Quick Start

# Install
uv sync

# Run the MCP server
uv run looplens-mcp

🔌 Claude Code Integration

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "looplens": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/looplens-mcp", "looplens-mcp"],
      "env": {
        "LOOPLENS_LOG_LEVEL": "INFO"
      }
    }
  }
}

⚙️ Configuration

All settings use the LOOPLENS_ prefix:

🔧 MCP Tools Reference

🔁 Loop Types Detected

• infinite — same tool called with identical input repeatedly

• oscillating — alternating between states without converging

• thrashing — high-frequency oscillation across many tools

• stuck — no meaningful progress for extended period

• tool_retry — same tool retried after repeated failures

🏗 Architecture

looplens/
├── server/          # MCP server wiring (app.py, __main__.py)
├── tools/           # 16 MCP tool handlers
├── resources/       # 4 MCP resource handlers
├── prompts/         # 3 MCP prompt builders
├── domain/          # Immutable domain models (Pydantic v2)
├── storage/         # SQLAlchemy 2.0 async repositories
├── ingestion/       # Event normalization pipeline
├── loop_detection/  # 4 detection algorithms + classifier + scorer
├── convergence/     # 5-metric scoring engine
├── analytics/       # Orchestrator for detection + convergence
├── security/        # Redactor, path guard, rate limiter
├── connectors/      # Claude Code, JSON, JSONL event parsers
└── exports/         # Eval case exporter

🌟 Why it matters

One of the biggest weak points in AI coding today is what happens after the first fix fails.

LoopLens helps make retries:

• measurable

• comparable

• diagnosable

• learnable

Instead of:

"try something else"

you get:

"Attempt 3 repeated the same failure signature as attempt 2, edited the same files, and did not reduce validation severity — likely retry loop. Best next step: gather more evidence before editing again."

That is the kind of debugging intelligence coding agents need.

🌍 Vision

LoopLens aims to become the iteration intelligence layer for agentic debugging:

• better local debugging

• better repair observability

• better eval datasets

• better failure analysis

• better coding-agent improvement loops

🧪 Status

Early project / active build.

If this resonates with you, ideas, contributions, and feedback are very welcome 🙌

📄 License

MIT

🔁🔍 LoopLens MCP

See the loop. Break the loop.