Ghostwriter is an intelligent code review platform that automatically analyzes GitHub Pull Requests and provides high-quality review feedback using AI agents, static analysis, and architectural profiling.
The system integrates directly with GitHub through webhooks and performs asynchronous code reviews without blocking developer workflows. By combining Abstract Syntax Tree (AST) analysis, AI-powered reasoning, and repository-wide architecture evaluation, Ghostwriter helps development teams maintain cleaner, more scalable, and more secure codebases.
Manual code reviews are often:
- Time-consuming
- Inconsistent across reviewers
- Unable to scale with growing repositories
- Focused on syntax rather than architecture
Ghostwriter addresses these challenges by automatically reviewing pull requests and generating contextual feedback, allowing developers to focus on higher-level engineering decisions.
- GitHub webhook integration
- Automatic review generation on PR creation/update
- Line-by-line review comments
- Local LLM-based code understanding
- Context-aware suggestions
- Refactoring recommendations
- Best practice enforcement
- Class and function extraction
- Dependency analysis
- Call graph generation
- Structural context understanding
Detects:
- God Classes
- Long Methods
- Duplicate Code
- Tight Coupling
- Circular Dependencies
- Excessive Nesting
- Dead Code
- Design Smells
- Queue-based task execution
- Scalable worker architecture
- Fault-tolerant job handling
- Repository health metrics
- Code quality trends
- Historical review reports
- Architecture score tracking
┌────────────────────┐
│ GitHub PR │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Webhook Receiver │
│ (FastAPI / Go) │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Message Queue │
│ Redis / RabbitMQ │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Worker Services │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ AST Parser │
│ AI Agent Workflow │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Review Generator │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ GitHub PR Comments │
└────────────────────┘
| Component | Technology |
|---|---|
| API Server | FastAPI / Go |
| Database | PostgreSQL |
| Authentication | GitHub OAuth |
| ORM | SQLAlchemy |
| Component | Technology |
|---|---|
| Message Queue | Redis / RabbitMQ |
| Task Workers | Celery |
| Caching | Redis |
| Component | Technology |
|---|---|
| LLM | Llama 3 |
| Local Inference | Ollama |
| Agent Framework | LangGraph / CrewAI |
| Parsing Engine | Tree-sitter |
| Analysis Language | Python |
| Component | Technology |
|---|---|
| Framework | React.js |
| Styling | Tailwind CSS |
| Charts | Recharts |
| API Communication | Axios |
| Component | Technology |
|---|---|
| Containerization | Docker |
| Orchestration | Docker Compose |
| CI/CD | GitHub Actions |
A developer opens or updates a Pull Request in GitHub.
GitHub sends a webhook event to Ghostwriter.
The backend validates the request and creates a review job.
The review task is pushed to Redis or RabbitMQ.
Workers:
- Fetch repository changes
- Parse code into AST
- Extract structural information
- Generate contextual code chunks
AI agents perform:
- Code quality analysis
- Security checks
- Architecture review
- Performance evaluation
Review comments and summary reports are created.
Generated feedback is posted directly to the Pull Request.
- Webhook Receiver
- API Development
- Authentication
- Job Creation
- Database Design
- GitHub Integration
- FastAPI / Go
- PostgreSQL
- Background Task Management
- Queue Architecture
- Worker Management
- Retry Handling
- Failure Recovery
- Redis
- RabbitMQ
- Celery
- AST Parsing
- Smart Code Chunking
- Context Extraction
- AI Agent Workflow Design
- Architecture Analysis
- Review Generation
- LangGraph
- CrewAI
- Ollama
- Llama 3
- Tree-sitter
- Dockerization
- Deployment Setup
- Monitoring
- Analytics Dashboard
- UI/UX Development
- Docker
- React.js
- Tailwind CSS
def calculate(users):
result = []
for user in users:
if user.active:
if user.has_permission:
if user.age > 18:
result.append(user)
return resultIssue: High nesting complexity detected.
Recommendation:
- Use guard clauses.
- Reduce cyclomatic complexity.
- Improve readability.
Suggested Refactor:
def calculate(users):
return [
user for user in users
if user.active
and user.has_permission
and user.age > 18
]- Repository Health Score
- Code Quality Trends
- Most Common Issues
- Pull Request Statistics
- Architecture Risk Indicators
- Review History
- Multi-language support
- Security vulnerability detection
- Test coverage analysis
- Technical debt scoring
- Repository-wide architecture graph
- AI-generated pull request summaries
- Automated refactoring suggestions
- Slack and Discord integrations
- Enterprise deployment support
- Multi-repository analytics
- Team performance insights
- Custom review policies
git clone https://github.com/your-org/ghostwriter.git
cd ghostwriter
docker-compose up --buildTo run the tests in your local environment, install the dependencies in a virtual environment and execute pytest:
# Create a virtual environment
py -m venv venv
# Activate and install dependencies
.\venv\Scripts\pip install -r requirements.txt
# Execute the test suite
.\venv\Scripts\python -m pytestIf you have Docker running, you can execute the tests inside the container environment:
# Build the test image
docker build -t ghostwriter-test .
# Run pytest inside the container
docker run --rm ghostwriter-test pytest- Member 1 – Backend & API
- Member 2 – Queueing & Infrastructure
- Member 3 – AI Agents & Code Parsing
- Member 4 – DevOps & Frontend Dashboard
MIT License
Ghostwriter aims to become an intelligent engineering assistant capable of understanding software architecture, reviewing code at scale, and helping teams ship higher-quality software faster.