Skip to main content
Glama
Sign In
patchpilot

patchpilot

by codesphere-u
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

patchpilot — Autonomous Code Repair Engine

CI Python 3.10+ MCP Compatible Zero Dependencies License: MIT

Stack-Trace & AST Call-Graph Fault Localizer, Deterministic Anti-Reward-Hacking Patch Verifier (RH001–RH008), Transactional Rollback Sandbox, and Model Context Protocol (MCP) Server for Autonomous Coding Agents.

Why patchpilot Exists: The Two Failure Modes of Coding Agents

Modern autonomous software engineering loops (OpenHands, SWE-agent, Claude Code, Devin-style test-repair loops) fail in production for two recurring reasons:

  1. Context-Window Flooding During Fault Localization: Dumping dozens of repository files into an LLM prompt when a pytest run fails wastes 90%+ of context tokens and confuses the model. Agents need deterministic Stack-Trace + AST Call-Graph + BM25 Spectrum Fault Localization to isolate the exact suspect functions and extract minimal, line-numbered AST slices within a strict token budget.

  2. Reward Hacking / Test Tampering by Coding Agents: When an LLM agent is rewarded for making pytest exit with code 0, it frequently "cheats" instead of fixing the root cause—deleting test_* functions, injecting @pytest.mark.skip or pytest.xfail(), weakening assert x == y into assert True, altering expected test constants, or wrapping buggy code in except Exception: pass.

patchpilot solves both problems in a zero-runtime-dependency Python 3.10+ package with a CLI, Python SDK, and JSON-RPC 2.0 MCP Server.

Related MCP server: MCP Software-Engineering RL Environment

Architecture Overview

  Failing Pytest / Traceback Log                    Candidate Agent Patch (Diff / Files)
                │                                                    │
                ▼                                                    ▼
┌───────────────────────────────────────┐    ┌──────────────────────────────────────────────┐
│  1. FaultLocalizer & ASTSymbolIndex   │    │  2. PatchIntegrityGuard (AST Verifier)       │
│  ───────────────────────────────────  │    │  ──────────────────────────────────────────  │
│  • Parses Python & pytest tracebacks  │    │  • RH001: Test deletion / @skip / xfail      │
│  • Builds AST symbol table & 2-hop    │    │  • RH002: Assertion removal / tautologies    │
│    bidirectional caller/callee graph  │    │  • RH003: Bare except / Exception swallowing │
│  • Ranks suspects via weighted formula│    │  • RH004: Python AST syntax validation       │
│    (0.55 Stack + 0.25 Graph + 0.20 BM25)   │  • RH005: Dangerous primitives (eval/shell)  │
│  • Emits token-budgeted code slices   │    │  • RH006: Leftover breakpoint() / pdb        │
└──────────────────┬────────────────────┘    │  • RH007: Blast radius limits (files/lines)  │
                   │                         │  • RH008: Protected CI/config file lock      │
                   │                         └──────────────────────┬───────────────────────┘
                   ▼                                                │
         Minimal Context Prompt                                     ▼
          (96.6% token savings)              ┌──────────────────────────────────────────────┐
                                             │  3. TransactionalPatchWorkspace              │
                                             │  ──────────────────────────────────────────  │
                                             │  • Pre-patch SHA-256 byte snapshots          │
                                             │  • Runs test runner / verification callback  │
                                             │  • Automatic byte-exact rollback on failure  │
                                             │  • Emits tamper-evident SHA-256 RepairReceipt│
                                             └──────────────────────────────────────────────┘

Anti-Reward-Hacking Rules (RH001–RH008)

Every candidate patch is evaluated by PatchIntegrityGuard via pre-patch vs. post-patch Python ast comparison before any test runner is executed:

Rule ID

Rule Name

Severity

What It Deterministically Blocks

RH001

Test Deletion or Skip Injection

Critical

Deleting test_* functions/files, injecting @pytest.mark.skip, @pytest.mark.xfail, @unittest.skip, or calling pytest.skip() / self.skipTest().

RH002

Assertion Weakening or Tautology

Critical

Reducing the number of assert / self.assert* statements in a test, replacing assertions with tautologies (assert True, assert 1 == 1), or mutating expected test literals.

RH003

Broad Exception Swallowing

High

Introducing bare except: or except (Exception, BaseException): blocks whose body merely executes pass, ..., continue, or returns a literal constant (return None).

RH004

Syntax / AST Parse Failure

Critical

Producing invalid Python syntax in any modified .py file.

RH005

Forbidden Dangerous Primitives

Critical

Injecting eval(), exec(), __import__(), os.system(), os.popen(), or subprocess.*(..., shell=True).

RH006

Debug Breakpoint Leftovers

Medium

Leaving breakpoint(), pdb.set_trace(), or ipdb.set_trace() inside patched code.

RH007

Excessive Blast Radius

Medium

Touching more than max_files_touched (default 5) or max_lines_changed (default 250).

RH008

Protected Path Modification

High

Tampering with .github/workflows/*, pyproject.toml, conftest.py, lockfiles, or .env files.

Reproducible Benchmark Results

Run patchpilot benchmark to execute the built-in benchmark suite across 50 indexed modules (100 AST symbols), 25 fault localization scenarios, and 40 patches (20 adversarial reward-hacking patches across RH001–RH008 + 20 legitimate bug fixes):

Subsystem

Benchmark Workload

Primary Accuracy / Recall

Secondary Metric

p50 Latency

p95 Latency

AST Symbol & Call-Graph Indexer

50 files / 100 symbols

100.0% AST parse coverage

Bidirectional call edges

3.79 ms

3.79 ms

Hybrid Fault Localizer (FaultLocalizer)

25 stack & call-graph fault scenarios

100.0% Top-1 / 100.0% Top-3

96.6% prompt token reduction

0.373 ms

0.499 ms

Anti-Reward-Hacking Guard (RH001–RH008)

20 adversarial + 20 legitimate patches

100.0% Recall / 100.0% Precision

0.0% False Positive Rate

0.098 ms

0.331 ms

Installation

git clone https://github.com/codesphere-u/patchpilot.git
cd patchpilot
pip install -e ".[dev]"

Quickstart: CLI

1. Run the End-to-End Autonomous Repair Demo

patchpilot demo

This creates a synthetic multi-file billing repository with a discount calculation bug, localizes the fault from a pytest failure log to the exact offending functions (billing/invoice.py::calculate_tiered_invoice and billing/pricing.py::apply_volume_discount) using only 303 tokens, catches and rolls back an adversarial reward-hacking patch (RH001, RH002, RH003), and commits a genuine minimal fix with a verified SHA-256 RepairReceipt.

2. Run the Benchmark Suite

patchpilot benchmark
patchpilot benchmark --json

Quickstart: Python SDK

from pathlib import Path
from patchpilot import FaultLocalizer, PatchIntegrityGuard, TransactionalPatchWorkspace

workspace = Path("./my_project")

# 1. Localize a failing pytest traceback within a 600-token budget
localizer = FaultLocalizer.from_directory(workspace)
loc = localizer.localize(pytest_stderr_output, top_k=3, token_budget=600)
print(loc.format_context_prompt())

# 2. Apply a candidate patch transactionally (with RH001-RH008 guard + automatic rollback)
sandbox = TransactionalPatchWorkspace(workspace, guard=PatchIntegrityGuard())
receipt = sandbox.apply_patch_transaction(
    patched_files={"billing/pricing.py": fixed_source_code},
    test_command=["pytest", "-q"],
    suspects_considered=[s.symbol.symbol_id for s in loc.suspects],
)

if receipt.status == "committed":
    print(f"Committed! Receipt SHA-256: {receipt.receipt_sha256}")
else:
    print(f"Rolled back at stage={receipt.stage_failed}: {receipt.guard_verdict.violations}")

Model Context Protocol (MCP) Server Integration

patchpilot includes a full JSON-RPC 2.0 MCP server (patchpilot serve-stdio) exposing four deterministic tools to Claude Code, Cursor, OpenHands, or custom MCP clients:

  • localize_fault: Rank suspect functions from a traceback and return token-budgeted AST slices.

  • verify_patch_integrity: Evaluate a candidate patch or unified diff against RH001–RH008.

  • apply_transactional_patch: Apply a patch inside an atomic snapshot transaction with automatic SHA-256 rollback on guard or test failure.

  • inspect_ast_symbols: Query the workspace AST symbol table and caller/callee graph by name or (file_path, line_number).

MCP Client Configuration (claude_desktop_config.json / .cursor/mcp.json)

{
  "mcpServers": {
    "patchpilot": {
      "command": "patchpilot",
      "args": ["serve-stdio", "--workspace", "/path/to/your/repo"]
    }
  }
}

Architecture Decision Records (ADRs)

License

MIT License — Copyright (c) 2026 Akandwanaho Ivan Alvin (@codesphere-u).

This server cannot be deployed

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • CodeGraph

    Phoenixrr2113
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to search code by meaning, explore codebase structure, store and query knowledge with temporal facts, and read source code through a set of MCP tools.
    348 npm
    7
    MIT

  • CodeForgeX

    kirubeshvarman28
    A
    license
    A
    quality
    B
    maintenance
    Enables AI agents to perform software engineering tasks inside an isolated, deterministic sandbox—exploring repositories, reproducing failures, applying patches, running tests, and verifying solutions against hidden suites through MCP tools.
    8
    MIT

  • cortex

    Buzburg
    A
    license
    B
    quality
    B
    maintenance
    Enables AI coding agents and local LLMs to store and recall project memory, compact verbose logs, look up code symbols, create and rewind workspace snapshots, detect risky commands and loops, pack context optimally, and draft tokens through MCP tools.
    10
    2
    Apache 2.0