Install & CLI
PatchPilot keeps its AST localizer, anti-reward-hacking guard, snapshot sandbox, and JSON-RPC 2.0 stdio server in pure Python standard library modules, with FastAPI/Uvicorn wired in pyproject.toml for the Streamable HTTP gateway.
Install Options
git clone https://github.com/codesphere-u/patchpilot.git cd patchpilot && pip install -e ".[dev]"
CLI Subcommands
| Command | Description |
|---|---|
patchpilot demo [--json] | Creates a billing bug workspace, ranks 3 AST slices in 303 tokens, blocks an adversarial patch, and commits the clean fix. |
patchpilot benchmark [--json] | Runs the 50-file AST indexer, 25-scenario localizer, and 40-patch guard benchmark. |
patchpilot audit-diff [file] [--json] | Audits unified diff input from a path or stdin against RH001–RH008; exits 1 on violation. |
patchpilot export-aegis [file] --task-id ID | Emits canonical Nexus Aegis G5_ANTI_REWARD_HACK attestation with RFC 6962 0x00 leaf hash. |
patchpilot serve-stdio / mcp | Runs the JSON-RPC 2.0 stdio MCP server with optional --workspace path. |
patchpilot serve-http --host 127.0.0.1 --port 8000 | Runs the local HTTP/SSE MCP server and developer portal. |
AST Guard (RH001–RH008)
PatchIntegrityGuard walks original and candidate Python ASTs side by side to detect test tampering, weakened assertions, swallowed exceptions, syntax failures, unsafe primitives, and protected config changes.
Rule Severities & Defaults
Protected patterns by default include .github/*, pyproject.toml, setup.py, poetry.lock, uv.lock, requirements*.txt, .env*, and conftest.py. Blast radius defaults to max_files_touched=5 and max_lines_changed=250.
from patchpilot import PatchIntegrityGuard
guard = PatchIntegrityGuard()
verdict = guard.verify_patch(
original_files={"tests/test_app.py": orig_test, "app.py": orig_app},
patched_files={"tests/test_app.py": cheated_test, "app.py": fixed_app},
)
assert not verdict.approved
Diff Audit & Nexus Aegis Export
Even without full repository files on disk, patchpilot.diff_parser.audit_unified_diff reconstructs added/removed hunks and checks every modified file in a PR or agent diff.
Fault Localizer SDK
Rather than dumping entire source trees into agent prompts, FaultLocalizer indexes AST functions, classes, and bidirectional call edges and selects only high-signal slices fitting your token budget.
Hybrid Ranking Signals
- Traceback Frames: Extracts standard Python tracebacks and pytest short failure traces.
- Bidirectional Call-Graph: Walks 1-hop callers and callees from crashing frames so root causes in helper functions rank alongside crash sites.
- BM25 Lexical Spectrum: Matches camelCase and snake_case identifiers from error messages and assertion lines.
Token Budget Packing
from pathlib import Path
from patchpilot import FaultLocalizer
localizer = FaultLocalizer.from_directory(Path("./repo"))
result = localizer.localize(pytest_stderr, top_k=3, token_budget=600)
print(result.format_context_prompt())
SHA-256 Sandbox
TransactionalPatchWorkspace guarantees that failed agent patches never leave half-edited files or broken state behind on disk.
Atomic Transactions
Before writing any byte, the sandbox records pre-state SHA-256 digests of targeted files. It evaluates PatchIntegrityGuard first, writes approved edits, runs your verification callback or test command, and rolls back byte-for-byte on non-zero exit or guard rejection.
RepairReceipt Schema
from patchpilot import PatchIntegrityGuard, TransactionalPatchWorkspace
sandbox = TransactionalPatchWorkspace("./repo", guard=PatchIntegrityGuard())
receipt = sandbox.apply_patch_transaction(
patched_files={"billing/pricing.py": new_source},
test_command=["pytest", "-q"],
)
print(receipt.status, receipt.receipt_sha256)
MCP & Vercel Gateway
PatchPilotMCPServer implements MCP JSON-RPC 2.0 (2024-11-05) with 5 tools, 2 resources, and 2 prompts over stdio, local HTTP/SSE, and Vercel ASGI.
Stdio & Local HTTP/SSE
python scripts/smoke_test.py https://patchpilot-eta.vercel.app 4 2 2
Hosted Guardrails
- Stateless Tools Allowed:
audit_unified_diff,verify_patch_integrity,localize_fault(inlinesources), andinspect_ast_symbols(inlinesources). - Blocked on Public Endpoint:
apply_transactional_patchand arbitraryworkspace_rootarguments are blocked inapi/index.py. - Request Cap & Headers: 1 MB body cap plus
X-Request-IDandX-Content-Type-Options: nosniffon every response.