Imagine this: You paste a GitHub Issue link into a dashboard and sip your coffee. While you watch, an AI autonomously clones your repository, hunts down the exact file causing the bug, and writes the fix. But it doesn't stop there—it spins up an isolated Docker sandbox, runs your tests to prove the fix works, and automatically opens a Pull Request for your review.
That is Ghost Coder. It's not just a chat wrapper; it's a relentless, autonomous software engineer that handles the mundane debugging so you can focus on building.
- ⚡ Quick Start & Installation
- 🏗️ System Architecture
- 🛠️ Technology Stack
- 🌱 Env Variables
- 👨💻 Developers & Troubleshooting
- 🙌 Contributing
- 📄 License
- Python 3.11+
- Docker Desktop installed and running
- Groq API Key and GitHub PAT
Ghost Coder supports installation via uv (recommended for speed) or standard pip.
-
Clone the repository
git clone https://github.com/NinadAmane/Ghost-Coder.git cd Ghost-Coder -
Install dependencies
Using uv (Recommended):
uv sync source .venv/bin/activate # Windows: .venv\Scripts\activate
Alternative using standard pip:
python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e .[dev]
Ghost Coder is built on a modular, multi-agent state-machine architecture powered by LangGraph. The workflow acts as a living cycle where agents collaborate, test, and loop until a solution is mathematically validated.
graph TD
Start((Start)) --> Researcher[Researcher Agent]
Researcher --> Coder[Coder Agent]
Coder --> Tester[Tester Agent]
Tester --> Sandbox{Docker Sandbox}
Sandbox -- Failure Feedback --> Coder
Sandbox -- Success --> PR[Human-in-the-Loop PR]
PR --> End((Finish))
subgraph "Orchestration Layer (LangGraph)"
Researcher
Coder
Tester
end
subgraph "Execution Environment"
Sandbox
end
| Component | Technology | Function |
|---|---|---|
| Brain | Groq (llama-3.3-70b-versatile) |
High-speed reasoning and code generation |
| Orchestration | LangGraph & LangChain | Multi-agent state machine looping |
| Frontend | Streamlit | Live, streaming agent-thought UI |
| Sandbox | Docker SDK | Secure, dependency-aware code execution |
| Version Control | PyGithub & Git | Automated branch and Pull Request creation |
| CI/CD | GitHub Actions | Automated Pytest validation & Docker builds |
The following environment variables are required for full functionality. You can input them in the Streamlit Sidebar or set them in a .env file at the root of the project.
| Variable | Description | Source |
|---|---|---|
GROQ_API_KEY |
API Key for Llama-3 reasoning | Groq Console |
GITHUB_TOKEN |
Personal Access Token for repo access | GitHub Settings |
To ensure the sandbox and core tools are functioning correctly, run the test suite:
pytest tests/⚠️ Troubleshooting Common Errors
Docker Connection Refused Ensure Docker Desktop is running and the Docker daemon is accessible to your terminal.
ModuleNotFoundError in Sandbox
If the agent fails to find a library (like pandas), ensure the target repository has a requirements.txt. The Docker Sandbox will automatically parse it and install dependencies before running the test.
Groq Rate Limits
If you encounter 429 Too Many Requests, the system will automatically retry, but you may need to check your Groq usage tier.
We welcome contributions! Please see our contributing guidelines for more details.
This project is licensed under the GNU AGPLv3 License. See the LICENSE file for details.
Architected and developed by Ninad Amane.
