CodeSentinel - Autonomous GitHub AI Agent

Tagline: Code that fixes code. AI agents building open source.

Overview

CodeSentinel is an intelligent GitHub agent that autonomously reads issues, plans fixes, updates code, validates changes, and creates pull requests — while also scoring community PRs by quality to help maintainers merge the best contributions.

Features

🔧 Issue to PR Workflow

• AI-Powered Issue Analysis: Uses Gemini 1.5 Flash to understand GitHub issues
• Intelligent Code Generation: Automatically generates code patches to fix issues
• Automated Validation: Runs pylint, black, and radon to ensure code quality
• Seamless PR Creation: Opens pull requests with detailed documentation
• Safety Guardrails: Repository whitelisting, file/line limits, validation requirements

📊 PR Quality Ranking

• Comprehensive Analysis: Fetches and analyzes all open pull requests
• Multi-Factor Scoring: Evaluates code quality, size, recency, and description
• AI-Powered Insights: Uses Gemini to assess PR quality and provide recommendations
• Actionable Rankings: Provides clear merge/review/needs-work recommendations

Architecture

┌─────────────────────────────────────────┐
│         Streamlit Dashboard              │
│   (Issue to PR | PR Ranking | History)   │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────┴───────────────────────┐
│          Agent Core Logic                │
│  (Orchestration & Workflow Management)   │
└─────────┬──────────────┬────────────────┘
          │              │
┌─────────┴────────┐  ┌──┴──────────────┐
│   Gemini AI      │  │  GitHub Client   │
│  - Issue Analysis│  │  - Repo Cloning  │
│  - Plan Gen      │  │  - PR Creation   │
│  - Patch Gen     │  │  - PR Fetching   │
│  - PR Scoring    │  │  - Diff Analysis │
└──────────────────┘  └──────────────────┘
          │
┌─────────┴────────────────────────────────┐
│         Validation Pipeline               │
│  (Pylint | Black | Radon | Safety Checks)│
└───────────────────────────────────────────┘
          │
┌─────────┴────────────────────────────────┐
│         Storage & Artifacts               │
│     (Run History | Rankings | Logs)       │
└───────────────────────────────────────────┘

Tech Stack

• Frontend: Streamlit (Python)
• AI Engine: Google Gemini 1.5 Flash
• GitHub Integration: PyGithub + GitPython
• Code Validation: Pylint, Black, Radon
• Storage: JSON-based file storage

Setup Instructions

1. Prerequisites

• Python 3.10+
• GitHub account with personal access token
• Google AI Studio API key (Gemini)

2. Required Secrets

Add these secrets in your Replit environment:

• GEMINI_API_KEY: Your Google AI Studio API key

  • Get it from: https://aistudio.google.com/app/apikey

• GITHUB_TOKEN: Your GitHub personal access token

  • Create at: https://github.com/settings/tokens
  • Required scopes: repo (full control of private repositories)

3. Running the Application

The application runs automatically on Replit. Access it via the web preview.

Usage Guide

Issue to PR Workflow

1. Navigate to the Issue to PR tab
2. Enter the GitHub repository URL (e.g., https://github.com/owner/repo)
3. Paste the issue description or problem statement
4. Click Run Agent
5. Watch the AI agent:
   • Analyze the issue
   • Generate a fix plan
   • Create code patches
   • Validate the changes
   • Create a pull request

PR Ranking

1. Navigate to the PR Ranking tab
2. Enter repository in format owner/repo
3. Click Analyze PRs
4. View ranked PRs with:
   • Overall quality scores
   • AI-powered insights
   • Merge recommendations
   • Detailed metrics

Safety Features

Built-in Guardrails

• File Limit: Maximum 10 files changed per PR
• Line Limit: Maximum 500 lines changed per PR
• Code Quality: Minimum lint score of 7.0/10
• Complexity: Maximum complexity checks
• Repository Whitelist: Optional repo access control

Validation Pipeline

Every code change is validated through:

• Pylint: Python code quality and style
• Black: Code formatting compliance
• Radon: Cyclomatic complexity and maintainability index

Project Structure

.
├── app.py                 # Streamlit dashboard
├── agent_core.py          # Main agent orchestration
├── gemini_ai.py          # Gemini AI integration
├── github_client.py      # GitHub API client
├── validators.py         # Code validation pipeline
├── pr_scorer.py          # PR quality scoring
├── storage.py            # Run history & artifacts
├── config.py             # Configuration & guardrails
└── runs/                 # Stored run data
    ├── index.json        # Run index
    ├── {run_id}/         # Individual run artifacts
    └── rankings/         # PR ranking results

Demo Flow

1. Home: Overview and metrics
2. Issue to PR: Submit an issue → Watch AI agent work → Get PR link
3. PR Ranking: Analyze repository → View ranked PRs → See recommendations
4. Run History: Review past agent runs
5. Configuration: Check API keys and settings

Development Roadmap

Phase 1 (MVP) ✅

• Issue analysis and code patch generation
• GitHub PR creation automation
• PR quality scoring and ranking
• Streamlit dashboard
• Safety guardrails

Phase 2 (Future)

• Time-based scheduling for automated repo sweeps
• GitHub webhook integration for real-time events
• Advanced security scanning with Semgrep
• Pytest integration for test validation
• Multi-repository monitoring dashboard
• Email/Slack notifications for recommendations

Credits

Team: Scaletron AI Collective
Location: India
Project Lead: Utkarsh Bahuguna

Built for the Agentverse - The Era of Autonomous AI Hackathon.

License

MIT License - Built for educational and demonstration purposes.