CodeSentinel
Ayush3300/CodeSentinel
Revisor automático de PRs que detecta bugs e issues em paralelo
Ver no GitHubAgent de IA que revisa automaticamente Pull Requests no GitHub, identificando bugs, problemas de qualidade de código e cobertura de testes. Funciona como um engenheiro sênior, postando comentários inline detalhados com explicações e sugestões de correção em segundos.
Instalação
npx convez-ai Ayush3300/CodeSentinel1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar reviews técnicos de Pull Requests
- Identificar bugs e problemas de segurança antes do merge
- Garantir qualidade de código com padrões consistentes
- Detectar cobertura insuficiente de testes
Veredito

Solução robusta e prática para CI/CD que automatiza reviews de código com múltiplos agentes especializados. Exige setup técnico (Groq API, webhooks GitHub, Railway) mas entrega valor real ao eliminar reviews manuais repetitivas.
README
A tradução para o português deste README ainda está na fila.
CodeSentinel
An AI agent that reviews your Pull Requests like a senior engineer — in under 30 seconds.
Built with Groq, FastAPI, and GitHub Webhooks. Catches bugs, security issues, and missing tests by running parallel specialist agents on every PR diff.
What it does
When a PR is opened or updated, the agent automatically:
- Fetches and parses the diff into file-level chunks
- Runs 3 specialist AI agents in parallel — code quality, logic/security, test coverage — using Groq's LLaMA 3.3 70B model
- Each finding includes a category, title, detailed explanation (written like a senior engineer mentoring a junior dev), and a concrete code fix
- Aggregates findings into a structured summary (Breakdown by severity, By Category) and posts it as the overall PR review
- Posts inline comments on exact diff lines with severity, category, explanation, and suggested fix
Architecture
PR opened / new commit pushed
│
▼
GitHub Webhook (pull_request event)
│
▼
FastAPI Webhook Server (Railway)
│
┌──────┼──────┐
▼ ▼ ▼
Code Logic Test
Quality & Coverage
Agent Bugs Agent
Agent
│ │ │
└──────┼──────┘
▼
Aggregator (Groq summary)
(merge · deduplicate · rank)
│
▼
GitHub Reviews API
(inline comments + verdict)
Tech Stack
| Layer | Technology |
|---|---|
| Web framework | FastAPI + Uvicorn |
| LLM | Groq API (llama-3.3-70b-versatile) |
| Agent orchestration | Custom async pipeline (asyncio) |
| GitHub integration | PyGithub + Webhooks |
| Deployment | Railway (Docker) |
| Language | Python 3.11+ |
Getting Started
Prerequisites
Note: Each person running this agent needs their own free Groq API key and GitHub token. This lets the agent act on your own repositories without sharing credentials.
- Python 3.11+
- A Groq API key
- A GitHub personal access token with
reposcope (for private repos) orpublic_repo(for public repos) - A random
WEBHOOK_SECRETstring for GitHub webhook signature verification
1. Clone and install
git clone https://github.com/Ayush3300/CodeSentinel.git
cd CodeSentinel
pip install -r requirements.txt
2. Configure environment variables
Copy .env.example to .env and fill in your values:
GROQ_API_KEY=your_groq_api_key_here
GITHUB_TOKEN=your_github_token_here
WEBHOOK_SECRET=your_random_secret_here
3. Run locally
uvicorn main:app --reload --port 8000
The server starts at http://localhost:8000. Health check: GET /.
4. Expose the webhook (local dev)
For local development, use a tunnel such as ngrok to expose port 8000:
ngrok http 8000
Then add a webhook in your GitHub repo:
- Payload URL:
https://<your-tunnel-url>/webhook - Content type:
application/json - Secret: same value as
WEBHOOK_SECRET - Events: Pull requests
ngrok is optional and only needed for local development. For production, deploy to Railway (see below).
Live Deployment
This project is deployed on Railway and runs 24/7. To point it at your own repo:
- Fork this repo and deploy to your own Railway project
- Add your
GROQ_API_KEY,GITHUB_TOKEN, andWEBHOOK_SECRETas Railway environment variables - Generate a public domain in Railway (Settings → Networking → Generate Domain)
- Add a webhook in your target repo pointing to
https://your-app.up.railway.app/webhookwith the sameWEBHOOK_SECRET - Select Pull requests as the event
Project Structure
.
├── main.py # FastAPI webhook server
├── agents/
│ ├── orchestrator.py # End-to-end review coordinator
│ ├── code_quality.py # Code quality specialist agent
│ ├── logic_bug.py # Logic & security specialist agent
│ └── test_coverage.py # Test coverage specialist agent
├── core/
│ ├── diff_parser.py # Parse unified diffs into chunks
│ ├── aggregator.py # Merge, deduplicate, summarize findings
│ └── github_client.py # GitHub API (diff fetch, post review)
├── prompts/
│ └── review_prompt.py # LLM prompt templates
├── Dockerfile
├── requirements.txt
└── .env.example
How the agent pipeline works
- Webhook — GitHub sends a
pull_requestevent (openedorsynchronize) toPOST /webhook. The server verifies the HMAC signature and kicks off a background review task. - Fetch diff —
GithubClientdownloads the raw unified diff for the PR head commit. - Parse & chunk —
parse_diff()splits the diff into per-fileDiffChunkobjects;chunk_large_diff()splits oversized patches. - Parallel agents — Three specialist agents run concurrently via
asyncio.gather(), each calling Groq (llama-3.3-70b-versatile) with a tailored prompt. - Aggregate — Findings are deduplicated by
(filename, line), ranked by severity, and a verdict is chosen (APPROVE/COMMENT). - Summarize —
format_summary()calls Groq again withsummary_prompt()to produce a structured markdown review body. - Post review — Inline comments (with category, title, explanation, fix) and the summary are submitted via the GitHub Reviews API.
What I learned
- Designing structured LLM prompts that return rich, mentor-style explanations (category, title, explanation, fix) instead of one-liners
- Debugging webhook signature verification and environment variable propagation on Railway
- Switching LLM providers (Gemini → Groq) due to rate limits, and designing the codebase to make this swap straightforward
- Deploying a FastAPI + Docker app to Railway with persistent webhooks
- Running multiple specialist agents in parallel with
asynciowhile pacing API calls to stay within rate limits - Parsing GitHub unified diffs and mapping findings to exact line numbers for inline review comments
License
MIT