Self-Healing Bug Agent

Inspiration

Software teams spend a surprising amount of time handling failed CI pipelines. A developer must read the logs, reproduce the failure locally, identify the root cause, modify the code, write a regression test, rerun the test suite, and finally open a pull request.

AI coding assistants can suggest fixes, but suggestions are not the same as verified solutions. A model may produce code that looks correct while failing to compile, breaking another feature, or never addressing the original issue.

We wanted to build something more reliable: an agent that does not simply explain a stack trace, but actually runs the code, fixes the bug, verifies the result, and only reports success when the evidence supports it.

That idea became the Self-Healing Bug Agent, an autonomous debugging system built around a closed verification loop.

What it does

The agent is triggered by either a bug report or a failed GitHub CI workflow.

It then:

1. Checks out the exact failing commit.
2. Creates an isolated sandbox environment.
3. Runs the failing command to reproduce the issue.
4. Collects logs, stack traces, and repository context.
5. Analyzes the likely root cause.
6. Modifies the source code.
7. Generates a regression test that would have caught the bug.
8. Runs the new test and the full test suite.
9. Retries the repair when verification fails.
10. Opens a draft pull request only when all required checks pass.

The core workflow is:

CI Failure
    ↓
Reproduce
    ↓
Analyze
    ↓
Fix + Generate Test
    ↓
Independent Verification
    ↓
Pass → Open PR
Fail → Retry

The repair agent is not allowed to approve its own work. A separate verifier reruns the project from a clean environment and uses actual command results, exit codes, and test output to decide whether the fix is valid.

How we built it

We designed the project as a modular agent workflow rather than one large prompt.

A GitHub webhook receives failed workflow events and sends them to the backend orchestrator. The orchestrator creates a task, tracks its state, and coordinates each stage of the repair process.

The main components are:

• GitHub integration: receives CI events, retrieves repository information, and creates draft pull requests.
• Orchestrator: manages the workflow, state transitions, retries, and failure handling.
• Sandbox manager: checks out the repository and executes commands in an isolated environment.
• Planner and repair agent: analyzes logs, identifies relevant files, and proposes code changes.
• Test generator: creates a regression test for the reported failure.
• Independent verifier: reruns tests, linting, type checks, and other project-specific validation commands.
• Retry controller: feeds failed verification results back into the repair loop.
• Reporting layer: records patches, test output, attempts, logs, and the final result.

We used GitHub webhooks for event-driven execution and an agent orchestration framework such as LangGraph or the OpenAI Agents SDK to model the workflow as a state machine.

Each bug-fix task maintains information such as:

{
    "repository": "...",
    "commit_sha": "...",
    "failure_logs": "...",
    "diagnosis": "...",
    "changed_files": [],
    "generated_tests": [],
    "attempt_count": 0,
    "verification_result": "...",
    "status": "..."
}

This allows the system to preserve context across multiple repair attempts instead of starting from scratch after every failure.

Challenges we faced

Reproducing failures reliably

A CI failure may depend on a specific commit, dependency version, environment variable, operating system, or test command. Reproducing the same issue in a sandbox was one of the most important engineering challenges.

We addressed this by checking out the exact failing commit, using isolated environments, and storing the commands and logs produced during reproduction.

Preventing false success

Language models can confidently describe a fix as successful without executing it. For this project, model confidence was never treated as proof.

Success is determined by observable evidence:

exit_code = 0
required_tests = passed
regression_test = passed
quality_checks = passed

Only the independent verifier can mark a task as successful.

Managing iterative repair

The first patch is not always correct. The system therefore needs to understand verification failures and use them in the next attempt.

We built a bounded retry loop that records previous patches, failed commands, and new logs. This gives the repair agent additional evidence while preventing infinite execution.

Integrating multiple modules

The project combines GitHub events, repository management, sandbox execution, model reasoning, code editing, test generation, and pull-request creation.

Defining clear interfaces between these modules was essential. Without consistent inputs and outputs, an autonomous workflow quickly becomes a collection of disconnected scripts.

Balancing autonomy and safety

Automatically modifying repositories introduces real risks. We limited the agent by using isolated execution, maximum retry counts, draft pull requests, transparent logs, and human escalation when the issue cannot be verified.

What we learned

The biggest lesson was that reliable agents require more than strong model outputs.

A useful software engineering agent needs:

• Tools that can execute real commands.
• Persistent state across multiple steps.
• Clear success and failure conditions.
• Independent verification.
• Bounded retries.
• Transparent logs.
• A safe path for human intervention.

We also learned that orchestration is as important as code generation. The model may propose a patch, but the surrounding system determines whether that patch is tested, trusted, retried, or rejected.

Most importantly, we learned that the value of an autonomous coding agent is not merely its ability to write code. Its value comes from its ability to produce verified outcomes.

What makes it different

Most AI coding tools stop after suggesting a solution.

Our system completes the full engineering loop:

Write → Run → Check → Learn → Retry → Verify

The Self-Healing Bug Agent does not ask developers to trust its explanation. It provides the patch, the regression test, the execution logs, and the verification result before opening a pull request.

Built With

• actions
• agentic
• agents
• ai
• api
• code
• codex
• docker
• fastapi
• generation
• github
• langgraph
• openai
• python
• rest
• sdk
• webhooks