GitResolve is an autonomous, verification-centric AI issue investigation and repair platform for Python repositories. It analyzes issues, builds an actionable investigation plan, reproduces faults, verifies candidate patches in a hardened Docker sandbox, and creates draft GitHub pull requests only after explicit human approval.
Overview • Showcase • Workflow Architecture • Components • Deployment • Run Locally
GitResolve turns a GitHub issue or a direct bug report into a reviewable, fully-tested repair workflow. It gathers repository context, develops an investigation plan, checks whether the reported failure can be reproduced, and validates a proposed patch inside an isolated Docker sandbox before asking for approval.
The workflow has two explicit human gates:
- Gate 1 — Approve the plan before repair execution begins. Developers can engage in interactive multi-turn dialogue with the agent to clarify constraints or refine the approach.
- Gate 2 — Approve the exact verified diff before GitHub publication. Developers inspect the full diff, reproduction evidence, and test receipts.
Approval is cryptographically bound to the diff hash that was reviewed. Any subsequent change invalidates the approval and requires re-verification. GitResolve creates draft pull requests; it never auto-merges into target repositories.
Select from your installed GitHub repositories, inspect open issues, and trigger repairs with a single click.
Before any code changes occur, review the agent's structured investigation plan, budget allocation, and discuss adjustments in natural language.
Watch the agent worker execute baseline tests, fault localization, test reproduction, and patch generation with real-time streaming telemetry.
Inspect the verified diff hash and test receipts. Upon your authorization, GitResolve publishes a clean draft Pull Request to GitHub.
flowchart TD
subgraph Ingestion ["1. INGESTION & PLANNING"]
A["GitHub Issue or Bug Report"] --> B["FastAPI Control Plane: Validate & Store Task"]
B --> C["Asynchronous Worker Claims Distributed Lease"]
C --> D["LangGraph Planning Engine"]
D --> E["Structured Investigation Plan & Budget"]
end
subgraph Gate1 ["GATE 1: HUMAN PLAN REVIEW"]
E --> G1{"Developer Plan Review<br/>(Interactive Dialogue)"}
G1 -- "Request Re-plan / Clarify" --> D
G1 -- "Reject / Cancel" --> X1["Task Cancelled"]
G1 -- "Approve Plan" --> F["Dispatch Repair Phase"]
end
subgraph SandboxExecution ["2. HARDENED DOCKER SANDBOX REPAIR LOOP"]
F --> G["Acquire Pinned Git Snapshot"]
G --> H["Launch Ephemeral Docker Container<br/>(No Network, No Host Secrets, Read-Only FS)"]
H --> I["Execute Baseline Test Suite"]
I --> J["Agent Fault Localization & Minimal Reproduction Test"]
J --> K["Propose Constrained Code Patch"]
K --> L["Sandbox Verification: Full Suite + Regression Test"]
L --> M{"Deterministic Policy & Safety Gate"}
M -- "Tests Fail / Scope Exceeded" --> N["Iterate / Backtrack Repair"]
N --> K
end
subgraph Gate2 ["GATE 2: HUMAN DIFF APPROVAL"]
M -- "Verified Patch" --> G2{"Developer Diff Approval<br/>(Review Exact Diff Hash & Test Receipts)"}
G2 -- "Reject Patch" --> N
G2 -- "Approve Exact Diff" --> O["Publication Phase Dispatched"]
end
subgraph Publication ["3. GITHUB PUBLICATION"]
O --> P["Cryptographic Hash & Receipt Re-validation"]
P --> Q["Create Isolated Fix Branch"]
Q --> R["Commit Verified Patch"]
R --> S["Open Draft Pull Request on GitHub"]
end
classDef gate fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
classDef success fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#f8fafc;
class G1,G2 gate;
class S success;
GitResolve separates the user-facing web application, control plane, asynchronous agent worker, external integrations, and repository execution boundary. The API coordinates requests and persists task state; repository code is run exclusively inside hardened Docker containers.
| Component | Responsibility | Isolation Boundary |
|---|---|---|
| Frontend | Next.js 14 web client: Firebase Google auth, GitHub installation flow, task timeline, interactive plan review, and diff inspection. | Firebase sign-in and backend GitHub sessions are strictly decoupled. The browser never receives GitHub App private keys. |
| API · backend guide | FastAPI control plane: versioned REST API, request validation, authentication, ownership checks, task lifecycle, and event streaming. | Never executes repository code. Dispatches jobs to durable persistence without blocking on execution. |
| Services · store | Task transitions, policy enforcement, GitHub access management, and persistence abstractions. | Firestore access is isolated behind typed store interfaces. Repository permissions are validated directly against GitHub. |
| Worker | Background runner: claims plan, execute, and publication phases; maintains distributed leases; handles cancellation. | Runs outside API request threads; production deployments run on dedicated VM instances sharing durable Firestore storage. |
| Agent runtime · model router | Dual LangGraph workflows (planning & repair), typed state, tool schemas, and task-scoped token budgets. | Agent output constitutes evidence/proposals; backend policy gates determine task transitions. Model calls route through ModelRouter. |
| GitHub integration · setup guide | Installation-scoped OAuth tokens, repository syncing, and PR publication. | Publication re-validates the approved diff hash, base SHA, and trusted Docker verification receipt. |
| Sandbox | Hardened execution runner: acquires pinned repository snapshots, prepares wheel dependencies, and runs tests in Docker. | Receives no host credentials or Docker socket; execution runs with network disabled. |
GitResolve is architected as a resilient, decoupled cloud system deployed across Google Cloud Platform and Vercel:
flowchart TD
Frontend["Next.js 14 Frontend - Vercel Edge Network"]
API["FastAPI Control Plane - Google Cloud Run"]
Firestore[("Google Cloud Firestore - Transactional Task Store")]
subgraph GCE ["Google Compute Engine VM (e2-standard-4)"]
Worker["GitResolve Agent Worker - Async Daemon"]
Sandbox["Hardened Docker Sandbox - Isolated Container"]
Worker --> Sandbox
end
External["External APIs - Google GenAI & GitHub App"]
Frontend -- "HTTPS REST (Firebase Bearer Token)" --> API
API -- "ACID Task State & Events" --> Firestore
Worker <-- "Distributed Lease Polling & State Updates" --> Firestore
Worker -- "Model Routing & PR Publication" --> External
- Frontend on Vercel: Hosted at
gitresolve-agent.vercel.app, delivering edge-cached static assets, dark-mode terminal aesthetics, and reactive polling for real-time lifecycle event logs. - API on Google Cloud Run: Containerized FastAPI service with automated HTTPS, autoscaling, and secure environment variable injection via Google Secret Manager.
- Worker on Google Compute Engine (GCE): Dedicated Ubuntu VM (
e2-standard-4) hosting the persistent background daemon and the local Docker daemon required for untrusted repository code execution. - Persistence on Google Cloud Firestore: Central document database enforcing ACID transactions for distributed worker leases, task status transitions, and immutable event streams.
- LLM Routing via Google GenAI: Powered by Gemini 2.5 and 3.8 Flash via a specialized
ModelRouterenforcing per-task token quotas, bounded retries, and fallback handling.
- Untrusted Inputs: Model responses and repository contents are treated as untrusted input.
- Independent Policy Gates: Deterministic scope and diff checks, verification receipts, and backend approval gates—not model confidence—control whether a patch can be published.
- Container Isolation: Repository commands and tests run in Docker, never on the API or worker host. Execution containers run with network disabled and receive no host credentials.
- Diff Hash Integrity: The exact SHA-256 hash of the unified diff approved by the developer must match the publication payload byte-for-byte.
- Supported Targets: Currently optimized for Python 3.12 repositories on Linux x86-64 using
pytestand StreamlitAppTest.
| Limit | Value | Where it's defined (file/constant) |
|---|---|---|
| Max model calls per task | 50 |
backend/app/core/config.py (Settings.max_model_calls), backend/app/services/policy.py (HARD_CAPS["maxModelCalls"]) |
| Max repair attempts per task | 6 (cap: 1–12) |
backend/app/core/config.py (Settings.max_repair_attempts), backend/app/services/policy.py (HARD_CAPS["maxRepairAttempts"]) |
| Max tool calls per task | 120 |
backend/app/agent/graph_engine/state.py (DEFAULT_MAX_TOOL_CALLS) |
| Max graph steps per task | 240 |
backend/app/agent/graph_engine/state.py (DEFAULT_MAX_GRAPH_STEPS) |
Max specialist (gemini-4-argon) calls |
2 |
backend/app/agent/graph_engine/state.py (MAX_SPECIALIST_CALLS_PER_TASK) |
| Input / output token budget | 300,000 / 40,000 tokens |
backend/app/agent/graph_engine/state.py (DEFAULT_MAX_INPUT_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS) |
| Diff scope limit | 5 files, 150 lines (400 max w/ deletions) |
backend/app/core/config.py (Settings.max_diff_files, Settings.max_diff_lines), sandbox/models.py (ExecutionRequest.max_diff_lines) |
| Sandbox command timeout | 60s default (300s max) |
sandbox/models.py (ExecutionRequest.timeout_seconds), backend/app/core/config.py (Settings.execution_timeout_seconds) |
| Task execution timeout | 1,800s (30 min) |
backend/app/core/config.py (Settings.task_timeout_seconds) |
| Worker lease / heartbeat | 90s lease / 30s heartbeat |
backend/app/core/config.py (Settings.lease_seconds, Settings.heartbeat_seconds) |
| Daily task quota | 10 tasks/day |
backend/app/core/config.py (Settings.max_tasks_per_day) |
| API rate limits | 300 req/min per IP, 30 writes/min per user |
backend/app/core/config.py (Settings.rate_limit_per_minute_ip, Settings.rate_limit_writes_per_minute_user) |
- Python 3.12 and
uv - Node.js 18+ and npm
- Docker with Linux container support
From the repository root, install the Python environment:
uv sync --group devInstall frontend dependencies:
cd frontend
npm ci-
Start the API backend (from repository root):
uv run python -m uvicorn app.main:app --app-dir backend --reload --host 127.0.0.1 --port 8000
-
Start the frontend (from
frontend/):npm run dev
-
Verify endpoints:
- Web application:
http://localhost:3000 - API health check:
http://localhost:8000/health
- Web application:
Run the backend test suite:
uv run pytest -qRun frontend linting, typechecking, and production build:
npm --prefix frontend run lint
npm --prefix frontend run build- Frontend README — UI architecture, authentication, and state management
- Backend README — API endpoints, worker lifecycle, and persistence store
- Sandbox README — Execution contract, Docker profiles, and security boundaries
- GitHub App Integration — App manifest, webhook setup, and token exchange
- Product Requirements (PRD)
- Technical Requirements (TRD)
- Application Flow Document (AFD)
- Backend Schema & Lifecycle Contract
- UI/UX Design Brief
- Help & Troubleshooting Content
- Data Retention & Deletion Policy
- Privacy Policy
- Terms of Service
agent/ Model routing and shared agent utilities
assets/ Brand assets and application screenshots
backend/ FastAPI application, worker daemon, and test suites
docs/ System architecture, schemas, and compliance specifications
frontend/ Next.js 14 web application
githubapp/ GitHub App integration and publication services
sandbox/ Docker execution runner and verification profiles
scripts/ Operational and deployment scripts
GitResolve is publicly available for viewing and evaluation purposes. No open-source license is granted. Unauthorized copying, modification, redistribution, or commercial use of the source code is not permitted, except as allowed by applicable law or GitHub's Terms of Service.