README.md

metadata

title: AutoMaintainer
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false

AutoMaintainer

An Always-On Autonomous AI Software Engineering Team

AutoMaintainer is a revolutionary proof-of-concept that demonstrates an entirely autonomous, multi-agent software engineering team working natively inside your GitHub repositories.

Built with LangGraph, FastAPI, Next.js, and powered by Llama 3 (via Groq), this system doesn't just print code to a terminal—it brainstorms ideas, creates real GitHub Issues, writes code, submits Pull Requests, reviews the PRs, fixes its own bugs, and merges the code into your main branch.

Supabase Real-time Architecture Required! This repository was recently upgraded from a legacy WebSocket architecture to a high-performance Supabase Real-time Pub/Sub ecosystem. For this early access / open-source version, you must create a free Supabase project and provide the URL and API Keys in your .env files for the UI to receive logs from the AI agents. See the Database & Environment Setup section below for exact instructions!

(Note: In the upcoming official ecosystem launch, this will be handled automatically via a central cloud and users will simply run automaintainer login without needing to configure their own database!)

---

Features

• 5-Agent Hierarchy: Tasks are distributed across specialized agents (Architect, Visionary, Reviewer, Implementer, Maintainer).
• Native GitHub Integration: Agents communicate through real GitHub Issues, PR Comments, and Git Branches.
• Zero-Server Code Intelligence: Powered by GitNexus MCP, allowing agents to semantically navigate your repository and build Code Graphs without sending your code to a third-party server.
• Web IDE & Interactive Terminal: A fully integrated, VS Code-style Web IDE in the browser featuring an interactive PTY terminal connecting directly to the backend.
• Self-Correcting Iteration Loop: If the Maintainer AI rejects a PR, the Implementer AI reads the feedback and pushes a new commit to fix the bug!
• Real-time Observability UI: A sleek, dark-mode React dashboard connected via WebSockets allows you to monitor the AI Crew as they work in real-time.
• Blazing Fast: Powered by Groq's LPU inference, the entire cycle from Architecture to Merged PR can happen in under 20 seconds.
• Cloud Ready: Natively compatible with Hugging Face Spaces Docker deployments.

---

Quick Start

Option 1: Run via Docker (Recommended)

The fastest way to get started is by pulling the pre-built Docker image from the GitHub Container Registry. This includes both the Next.js frontend and FastAPI backend in a single container.

docker run -p 7860:7860 \
  -e GROQ_API_KEY="your_groq_api_key_here" \
  -e GITHUB_TOKEN="your_github_token_here" \
  ghcr.io/pxa-labs/automaintainer:latest

Open your browser to http://localhost:7860.

---

Option 2: Manual Setup

1. Prerequisites

• Node.js (v18+)
• Python (3.10+)
• A Groq API Key
• A GitHub Personal Access Token (with repo permissions)
• A Supabase Project (Free Tier is fine)

2. Database & Environment Setup

Clone the repository:

git clone https://github.com/PxA-Labs/AutoMaintainer.git
cd AutoMaintainer

Supabase Setup: Because AutoMaintainer now uses a high-performance Supabase Realtime architecture to stream logs to the UI:

1. Create a new Supabase Project
2. Go to your Supabase SQL Editor and run the provided supabase_schema.sql file located in the root of this repository. This creates the required runs and logs tables.
3. Grab your API keys from Project Settings -> API.

Create a .env file in the backend/ directory:

GROQ_API_KEY=your_groq_api_key_here
GITHUB_TOKEN=your_github_token_here
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your_secret_service_role_key

Create a .env.local file in the dashboard/ directory:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_public_anon_key
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000

3. Run the Backend (FastAPI + LangGraph)

Open a terminal and navigate to the backend directory:

cd backend
pip install -r requirements.txt
fastapi dev main.py

4. Run the Frontend (Next.js)

Open a new terminal and navigate to the dashboard directory:

cd dashboard
npm install
npm run dev

Note: In local development, the Next.js frontend runs on port 3000 and automatically proxies API traffic to the FastAPI backend running on port 8000. You can override this using the NEXT_PUBLIC_BACKEND_URL environment variable.

---

Usage

1. Open http://localhost:3000 in your browser.
2. In the sidebar under Configuration, click on the Target Repository and enter a repository you own (e.g., your-username/your-repo).
   • Note: Your GitHub Token must have push access to this repository!
3. Click Start Agents.
4. Watch the dashboard UI light up as the Architect scans your repo. Open your target repository on GitHub in another tab to watch the Issues and Pull Requests appear in real-time!

---

Architecture

Curious how it works under the hood? Read our Architecture Documentation to see how the 5-agent LangGraph topology operates.

---

Contributing

Want to add a new Agent or improve the dashboard? Check out our Contributing Guidelines.

---

License

This project is licensed under the MIT License.