AgentBisect MCP Server

💥 The Problem: "Compounding Agent Drift"

When you ask an autonomous coding agent (Claude Code, Cursor Agent, Google Antigravity, Devin, Cline, or Aider) to implement a multi-file feature or perform a large refactor, it executes 20 to 50 sequential steps (tool calls, file edits, bash commands).

Inevitably:

1. At Step 12, the agent makes a subtle semantic error (e.g., inverts an authorization check or changes a function signature).

2. Steps 13 to 40 turn into compounding hallucinations, writing broken patches on top of invalid assumptions.

3. At the end of the session, the test suite is completely broken.

Today, developers face a frustrating dilemma:

• Guess manually by reading through a 2,000-line JSON transcript.

• Or run git checkout . — wasting 40,000+ API tokens, $1.50+ in costs, and 30 minutes of waiting.

 Traditional:  [Step 1] ────────────────► [Step 12: BUG] ────────────────► [Step 40: FAIL] ❌
               └─── Wipe whole session (git checkout .)! 40k tokens wasted!

 AgentBisect:  [Step 1] ───► [Step 12: FIRST BAD] ───► [Step 11: FORK HERE] ───► [SUCCESS] ✅
               └─── Bisect isolated Step 12 in 5 test runs! Saved 28k tokens!

Related MCP server: Hoplon

🚀 The Solution: AgentBisect

AgentBisect brings deterministic binary search and time-travel trajectory debugging to AI coding agents:

1. Non-Polluting Shadow Git Ledger: Automatically snapshots workspace checkpoints inside .agentbisect/shadow_git/ without polluting your real .git log or creating unwanted branches.

2. Binary Search Trajectory Engine (agentbisect find): Locates the exact first broken step in $\mathcal{O}(\log_2 N)$ test executions (just 5 test runs for 32 steps).

3. Workspace & Context Forking (agentbisect fork <step>): Rewinds your filesystem to the last verified good step and synthesizes an intelligent post-mortem prompt (AGENT_FORK_PROMPT.md) for the agent to resume without repeating the error.

4. Self-Healing MCP Server & Skill: Agents running inside Cursor, Claude Desktop, or Antigravity can invoke agentbisect_bisect to autonomously debug and rewind themselves.

5. Interactive Local Web Dashboard (agentbisect ui): Full-featured dark-mode web dashboard with visual step graphs, side-by-side diffs, and token waste analytics.

6. Zero-Overhead Portable Evidence Bundles (agentbisect bundle export/import): Package faulty sessions as .bisect.zip for instant sharing and post-mortem review.

⚡ 10-Second Playground Demo

Try AgentBisect immediately without configuring any transcript or repo:

pip install agentbisect
agentbisect demo

(Also supports Node.js microservices via agentbisect demo --lang node)

This launches a pre-packaged simulation of an autonomous agent session, executes binary search live in your terminal, pinpoints the exact line broken at Step 12, and produces an interactive HTML report!

📦 Installation

Install via pip:

pip install agentbisect

Or install latest from source:

git clone https://github.com/test-bit-sys/agentbisect.git
cd agentbisect
pip install -e .

🔌 10-Second Setup on ANY Agent

AgentBisect can automatically configure itself for your preferred agent with a single command:

# 🎯 1-Click Auto Configuration:
agentbisect setup --agent cursor --write       # Configures .cursor/mcp.json
agentbisect setup --agent antigravity --write  # Installs skill in .gemini/skills/
agentbisect setup --agent claude --write       # Configures Claude Desktop
agentbisect setup --agent cline --write        # Configures .cline/mcp.json
agentbisect setup --agent windsurf --write     # Configures Windsurf MCP

# Or view snippets for all agents without writing:
agentbisect setup

🛠️ CLI Quick Reference

🤖 MCP Server Setup (Self-Healing Agent)

Enable your agent in Cursor, Claude Desktop, or Antigravity to debug itself:

Add to your MCP configuration (claude_desktop_config.json or Cursor Settings):

{
  "mcpServers": {
    "agentbisect": {
      "command": "agentbisect",
      "args": ["mcp"]
    }
  }
}

Available MCP Tools:

🛡️ Reliability & Correctness Guarantees

AI agent trajectories often break traditional debugging assumptions. AgentBisect incorporates formal reliability boundaries:

1. Explicit Regression Oracle

Every test evaluation distinguishes between:

• PASS: Exit code 0, test assertions satisfied.

• FAIL: Non-zero exit code indicating code assertion failure.

• INCONCLUSIVE: Command timed out or process hung without deterministic conclusion.

• ERROR: Infrastructure/environment defect (missing binary, permissions, OS failure). Infrastructure errors are never conflated with code regressions.

2. Non-Monotonic Trajectory Detection

Agents often introduce a bug at step $k$, partially patch it at step $m$, and break something else at step $n$. AgentBisect automatically monitors and detects non-monotonic inversions:

• CONFIRMED_FIRST_REGRESSION (95–99% confidence): Monotonicity holds, step $k-1$ passed, step $k$ failed.

• PROBABLE_FIRST_REGRESSION (80–90% confidence): Boundary identified with skipped unverified steps.

• EARLIEST_OBSERVED_FAILURE (65% confidence): Non-monotonic trajectory detected; identifies the earliest observed failure while highlighting that subsequent steps passed.

• INCONCLUSIVE: Infrastructure failures or flapping tests prevented deterministic diagnosis.

3. Flaky Test Mitigation & Stability Policies

Run tests with configurable retries (--retries N) and stability policies (--stability-policy majority or require_all_pass). Intermittent failures are never hidden; all execution attempts are recorded with timestamps, exit codes, and stdout/stderr.

4. Transactional Workspace Restoration

During bisection, files are safely evaluated. Your working tree—including uncommitted changes and untracked files—is transactionally stashed and guaranteed to be restored upon completion or keyboard interrupt. User .git directories and configurations are strictly protected from deletion.

5. Hardened Security & Isolation

• Zip-Slip Protection: Evidence bundle import validates every archive path against path traversal attacks (../), disallowing arbitrary file overwrites and symlinks outside .agentbisect/.

• Advisory File Locking: High-concurrency environments use atomic file locks (agentbisect.lock) to prevent concurrent ledger corruption between CLI, MCP, and Web UI.

• Atomic Persistence: Session metadata writes use atomic rename replacement to eliminate partial file corruption.

📊 Feature Comparison

🤝 Supported Agent Frameworks

• Google Antigravity & Gemini CLI (transcript.jsonl)

• Claude Code (.claude/ session transcripts)

• Cursor Agent / Composer

• Cline

• OpenHands / SWE-bench format

• Aider

• Generic JSON / JSONL Trajectories

🧪 Running Tests

pytest tests/ -v

📄 License

Distributed under the MIT License. See LICENSE for details.