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 🎯

---

🤔 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:

Variable	Default	Description
LOOPLENS_DATA_DIR	~/.looplens	Base data directory
LOOPLENS_DB_PATH	~/.looplens/looplens.db	SQLite database path
LOOPLENS_LOG_LEVEL	INFO	Log level
LOOPLENS_LOOP_FREQUENCY_THRESHOLD	3	Min repeats to flag a loop
LOOPLENS_LOOP_WINDOW_SIZE	20	Sliding window size for detection
LOOPLENS_REDACTION_ENABLED	true	Auto-redact secrets from payloads
LOOPLENS_RETENTION_DAYS	90	Days before old sessions are pruned

---

🔧 MCP Tools Reference

Tool	Description
create_session	Create a new debug session
get_session	Get session details
list_sessions	List sessions with filters
close_session	Mark session complete/abandoned
ingest_event	Record a single tool event
ingest_batch	Record multiple events at once
get_session_events	Retrieve session event history
detect_loops	Run loop detection algorithms
get_loops	Get detected loop patterns
mark_false_positive	Mark a false detection
get_convergence	Get convergence score
analyze_convergence_trend	Analyze trend over time
export_eval_cases	Export as eval dataset
get_diagnostics	Server health metrics
annotate_event	Add metadata to an event
search_events	Search by tool name

---

🔁 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.