Autonomous Bug-Fixing Agent
- Live Demo (AWS CloudFront HTTPS + EC2): https://d3gctx9v0f6g4u.cloudfront.net (http://98.89.45.201)
- Live Demo (Streamlit Cloud): https://autonomous-bug-fixing-agent.streamlit.app
An autonomous Python bug-fixing agent orchestrated with LangGraph and powered by Groq. It ingests a GitHub issue or bug report, inspects a repository, writes a failing pytest reproduction test, executes tests in an isolated sandbox, iterates on search/replace code fixes (up to 8 attempts), and pauses for human-in-the-loop approval before committing or exporting a patch.
How It Works
flowchart TD
A[ingest_issue] --> B[inspect_repo]
B --> C[write_repro_test]
C --> D[run_repro_test]
D -->|fails as expected| E[propose_fix]
D -->|passes: not reproduced| C
E --> F[apply_fix] --> G[run_tests]
G -->|pass| H[human_approval -- interrupt]
G -->|fail, under 8 iterations| I[analyze_failure] --> E
H -->|approve| J[commit_and_pr]
H -->|reject + feedback| I
The full architecture specification is in SPEC.md.
Core Agent Pillars
| Pillar | Implementation |
|---|---|
| LLM | Groq (openai/gpt-oss-120b) with structured JSON outputs (src/agent/llm.py) |
| Framework | LangGraph state machine & conditional edge routers (src/agent/graph.py) |
| Memory | AgentState + MemorySaver / PostgresSaver checkpointing (src/agent/state.py) |
| Tools | Path-jailed Workspace, Git/GitHub REST API & Sandbox test runners (src/tools/, src/sandbox/) |
Key Features
- LangGraph Orchestration (src/agent/graph.py, src/agent/state.py): Explicit
TypedDictstate with Pydantic v2 sub-models, pure conditional edge routers, andMemorySaver/PostgresSavercheckpointing. - Groq Free-Tier Guardrails (src/agent/llm.py, src/agent/prompts.py):
tenacityexponential backoff for 429 rate-limit and transient API errors.- Hard cap of 8 fix iterations (
RunBudget). - Active context pruning (
summarize_past_attempts) and tail-truncated sandbox outputs to stay well under Groq's 8K tokens/min free tier. - Structured JSON output validation with automatic repair.
- Pluggable Sandbox (src/sandbox/):
DockerSandbox(src/sandbox/docker_runner.py): Locked-down container (non-root user,cap_drop=["ALL"], memory/CPU/PID limits, network disabled).LocalSandbox(src/sandbox/local_runner.py): Subprocess fallback for environments without a Docker daemon (e.g., Streamlit Community Cloud), with environment secret scrubbing and process-tree timeout kills.
- Path-Jailed Workspace (src/tools/file_tools.py): Works on an isolated copy (
base/+work/) so your target repository is never modified until approval. Supports built-in sample repos, local folders, or shallow-cloning any GitHub repository URL. - Single-URL Repository Audit & PDF Report (src/ui/streamlit_app.py, src/ui/report_pdf.py): Paste a single GitHub repository URL to scan all files for bugs/defects, view a side-by-side Before/After diff and live telemetry bar, and download a printable PDF audit & fix report.
- Human-in-the-Loop Gate (src/agent/nodes.py):
commit_and_pris reachable only afterhuman_approvalresumes fromlanggraph.types.interrupt().
Project Layout
src/
agent/ state.py · llm.py · prompts.py · nodes.py · graph.py
sandbox/ base.py · docker_runner.py · local_runner.py · factory.py · Dockerfile
tools/ file_tools.py · git_tools.py
ui/ streamlit_app.py · mock_graph.py · report_pdf.py
tests/
unit/ test_state.py · test_docker_runner.py · test_routing.py · test_mock_graph.py · test_streamlit_app.py
fixtures/ buggy_repo/
deploy/ cloudshell_deploy.sh · ec2_userdata.sh
Dockerfile · docker-compose.yml · SPEC.md · requirements.txt · pyproject.toml
Getting Started
python -m venv .venv
.\.venv\Scripts\Activate.ps1 # Linux/macOS: source .venv/bin/activate
pip install -e ".[dev,ui]"
copy .env.example .env # Set GROQ_API_KEY in .env
Optional — build the Docker sandbox image if running with Docker:
docker build -t bugfix-agent-sandbox:latest src/sandbox
Running the Streamlit Web App
streamlit run src/ui/streamlit_app.py
In the sidebar you can:
- Choose Live Groq Agent or Scripted Demo (no API calls).
- Select a repository source (Built-in sample buggy repo, Local folder path, or GitHub URL (shallow clone)).
- Enter the bug title & description, then click ▶️ Start run.
- Review the generated reproduction test, unified diff, and pytest output when the agent pauses at
human_approval, then click Approve, Request changes, or Reject.
Deploying to AWS Free Tier (EC2 + CloudFront HTTPS + S3 + DynamoDB + Lambda)
Run the one-command bootstrap scripts in AWS CloudShell (deploy/):
# 1. Launch EC2 Docker instance
curl -sSL https://raw.githubusercontent.com/farazmalik180/autonomous-bug-fixing-agent/main/deploy/cloudshell_deploy.sh | tr -d '\r' | GROQ_API_KEY="gsk_..." bash
# 2. Provision CloudFront HTTPS CDN
curl -sSL https://raw.githubusercontent.com/farazmalik180/autonomous-bug-fixing-agent/main/deploy/aws_https_cloudfront.sh | tr -d '\r' | bash
# 3. Provision S3 Report Bucket, DynamoDB Run History & Lambda Webhook
curl -sSL https://raw.githubusercontent.com/farazmalik180/autonomous-bug-fixing-agent/main/deploy/aws_free_tier_stack.sh | tr -d '\r' | bash
- Live AWS CloudFront HTTPS URL: https://d3gctx9v0f6g4u.cloudfront.net
- Live AWS EC2 Direct URL: http://98.89.45.201 (http://98.89.45.201:8501)
- Live AWS Lambda Webhook URL: https://xmo5agqoh4bd7gkxaahbbpiqi40mjqst.lambda-url.us-east-1.on.aws/
- AWS S3 Archive Bucket:
s3://bugfix-agent-reports-706999906997-us-east-1 - AWS DynamoDB History Table:
BugFixAgentRuns
Deploying to Streamlit Community Cloud
- Push this repository to GitHub.
- In share.streamlit.io, create a new app pointing to
src/ui/streamlit_app.py. - Under App settings → Secrets, add:
GROQ_API_KEY = "gsk_..." SANDBOX_BACKEND = "local"
Running the Tests
pytest
Tests marked docker execute real containers and are skipped automatically when no Docker daemon is reachable.
Roadmap
- Phase 0: Architecture specification (
SPEC.md) & project scaffolding - Phase 1:
state.py&docker_runner.pywith unit tests - Phase 2: Path-jailed
file_tools.py,git_tools.py, andlocal_runner.py - Phase 3: Groq client (
llm.py), context pruner (prompts.py), LangGraphnodes.py&graph.py - Phase 4 & 5: End-to-end verification on
tests/fixtures/buggy_repo& interactive Streamlit UI
Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support