🤖 GitHub Repository Multi-Agent Bug Fixer

🏆 Capstone Project — Kaggle's 5-Day AI Agents: Intensive Vibe Coding Course with Google (July 2026)

An autonomous 4-agent system powered by CrewAI and Google Gemini that audits a GitHub repository, identifies bugs, applies minimal code patches, and submits a Pull Request for review. The entire process is visualized in real-time through a dynamic Streamlit Dashboard.

🔗 Live Demo

⚠️ Note: If the app shows a loading screen on first visit, please wait 60 seconds — it auto-wakes from sleep mode. To run the pipeline, you will need your own GitHub Personal Access Token, a Gemini or OpenRouter API Key, and a target GitHub Repository URL — enter all three directly in the dashboard before starting.

---

🚀 Features

• Multi-Agent Collaboration: Sequential coordination between 4 specialized agents:
  1. Collector Agent: Fetches repository structure, files, commits, and issue descriptions.
  2. Analyzer Agent: Performs static analysis (Python AST checking, JavaScript evaluations) and reasons to identify critical bugs.
  3. Fixer Agent: Creates a bug-fix branch, applies precise patches, and pushes them to GitHub.
  4. Reviewer Agent: Validates changes, runs regressions, and automatically raises a Pull Request on GitHub.
• Interactive Dashboard: Run audits, check real-time terminal logs, and inspect outputs in structured tabs.
• Dual LLM Provider Support: Run directly using Google Gemini models (e.g. gemini-3.1-flash-lite, gemini-2.5-pro) or OpenRouter models (e.g. Qwen, LLaMA).
• 🎨 Premium Dark Theme: Sleek dark-mode aesthetic with rounded glassmorphic elements and high-contrast readability.
• 🔧 API Diagnostics Utility: Diagnose GitHub Access Permissions and query available Gemini models before starting audits.
• ♻️ Auto-Clean & Safety: Automatically cleans up intermediate outputs on new runs, with manual override controls.
• Robust Tool Orchestration: Scripts are self-healing (downstream agents automatically run preceding dependency scripts if intermediate files are missing).

---

🛠️ Prerequisites

• Python 3.11 installed on your system.
• A GitHub Personal Access Token (PAT) with repo scope permissions.
• A Google Gemini API Key (from Google AI Studio) or an OpenRouter API Key.

---

⚙️ Installation & Setup

Follow these steps to set up the project locally:

1. Clone the Repository

git clone <repository-url>
cd github-repo-multi-agent-bug-fixer

2. Configure Environment Variables

Copy the example configuration file and rename it to .env:

cp .env.example .env

Open the .env file in your editor and fill in your keys:

GITHUB_PERSONAL_ACCESS_TOKEN=your_actual_github_personal_access_token
GEMINI_API_KEY=your_actual_gemini_api_key

# Optional: If you intend to use OpenRouter instead of Google Gemini direct API
OPENROUTER_API_KEY=your_actual_openrouter_api_key

3. Setup MCP Configuration (Optional for AI Assistants)

If you are developing this project using an AI coding assistant like Antigravity (which supports Model Context Protocol), you can enable the assistant to interact directly with your GitHub repositories.

Copy the example MCP configuration file and rename it to .agents/mcp_config.json:

cp .agents/mcp_config.json.example .agents/mcp_config.json

Open .agents/mcp_config.json and replace YOUR_GITHUB_PERSONAL_ACCESS_TOKEN_HERE with your actual token.

4. Create a Virtual Environment & Activate It

• Windows (PowerShell):

  python -m venv .venv
  .venv\Scripts\Activate.ps1

• macOS / Linux:

  python3 -m venv .venv
  source .venv/bin/activate

5. Install Dependencies

pip install -r requirements.txt

---

🖥️ Running the Application

To launch the Streamlit dashboard, run:

streamlit run app.py

This will automatically open the application interface in your default web browser (usually at http://localhost:8501).

---

📁 Project Structure

├── .agents/                    # Agent specifications & configurations
│   ├── agents/                 # Markdown prompts for agent backstories
│   │   ├── collector-agent.md  # Backstory and profile for the Collector Agent
│   │   ├── analyzer-agent.md   # Backstory and profile for the Analyzer Agent
│   │   ├── fixer-agent.md      # Backstory and profile for the Fixer Agent
│   │   └── reviewer-agent.md   # Backstory and profile for the Reviewer Agent
│   └── skills/                 # Markdown prompts for agent task goals
│       ├── collector-skill/    # Task goals & collector instructions (SKILL.md)
│       ├── analyzer-skill/     # Task goals & static analyzer instructions (SKILL.md)
│       ├── fixer-skill/        # Task goals & fixer sandbox instructions (SKILL.md)
│       └── reviewer-skill/     # Task goals & PR validation instructions (SKILL.md)
├── .streamlit/                 # Streamlit application configurations
│   └── config.toml             # Custom theme and page settings
├── assets/                     # Visual architecture diagrams and media
├── scripts/                    # Actionable scripts wrapped by CrewAI
│   ├── collector.py            # Pulls codebase & metadata from GitHub
│   ├── analyzer.py             # Run AST checks and highlights logic bugs
│   ├── fixer.py                # Patches source files dynamically in-memory
│   └── reviewer.py             # Performs LLM QA review and commits changes to GitHub upon approval
├── AGENTS.md                   # Project constraints and agent workspace rules
├── CHANGELOG.md                # Detailed history of project features and optimizations
├── agent_runner.py             # CrewAI orchestration layer
├── app.py                      # Streamlit interactive dashboard UI
├── requirements.txt            # Project python dependencies
├── .env.example                # Template configuration file
└── README.md                   # This documentation file