# 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

```bash
# Install
uv sync

# Run the MCP server
uv run looplens-mcp
```

## 🔌 Claude Code Integration

Add to `~/.claude/settings.json`:

```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.**