🩺 RepoCheckAI

AI-powered GitHub Repository Health Analyzer
Built with the GitHub Copilot SDK — the same AI agent runtime that powers Copilot CLI.

Website • Quick Start • Features • How It Works • Commands • Documentation

---

📖 Overview

RepoCheckAI is your repository's AI doctor that diagnoses issues and prescribes solutions. It performs comprehensive health checks across 6 critical areas — documentation, developer experience, CI/CD, testing, governance, and security — delivering a detailed diagnosis with prioritized findings (P0/P1/P2) and actionable remediation steps.

Two Analysis Modes

Mode	Description	Use Case
🔍 Quick Scan	Analyzes via GitHub API (up to 20 file reads)	Fast checks, governance review
🔬 Deep Analysis	Full source scan using Repomix	Code quality, architecture review

---

✨ Features

🤖 AI-Powered Analysis 11+ AI Models — GPT-4o, Claude Sonnet 4, GPT-5.3-Codex, o3, and more Contextual Understanding — Adapts to your stack Evidence-Based — Every finding backed by file evidence	📊 Comprehensive Reports Health Score — Overall percentage (0-100%) Prioritized Findings — P0 (critical), P1 (high), P2 (suggestions) Actionable Steps — Code snippets included
💬 Interactive CLI Slash Commands — /analyze, /deep, /copy, /export Chat Interface — Ask follow-up questions Streaming Output — Real-time analysis	Auto-Publish Issues One-Click Issue Creation — --issue flag creates structured GitHub issues Prioritized Findings — P0/P1/P2 labels with detailed descriptions Team Collaboration — Automated tracking of repository health issues CI/CD Integration — Perfect for automated health checks
🔐 Security First Prompt Injection Protection — File content treated as data Token Management — Secure GitHub authentication No Data Storage — Analysis runs locally

📢 Publishing Features

Automatically publish analysis reports to GitHub as structured issues:

🚀 Auto-Create Issues for Each Problem Found

export GITHUB_TOKEN=ghp_xxx          # or REPOCHECKAI_GITHUB_TOKEN, as configured
repocheck analyze owner/repo --issue
# Creates: 🔴 [RepoCheckAI] docs: Missing README
#         🟠 [RepoCheckAI] ci: No CI/CD Pipeline
#         🟡 [RepoCheckAI] dx: Code Quality Issues

Each issue includes:

• Detailed description with evidence and impact assessment
• Actionable fix instructions with code examples
• Priority labels (P0/P1/P2) and category tags
• Full analysis context for team collaboration

💬 Interactive Mode

# Set token securely (recommended)
export GITHUB_TOKEN=ghp_your_token_here

# Or use gh CLI auth
gh auth login

# Then start interactive mode
repocheck chat
/analyze facebook/react --issue
/deep microsoft/vscode

Tip

Perfect for automated repository health tracking and team collaboration!

📖 Learn how to set up GitHub tokens

---

� Quick Start (5 minutes)

Want to see RepoCheckAI create GitHub issues automatically?

# 1. Get a GitHub token (see detailed setup below)
# 2. Set it as environment variable
export GITHUB_TOKEN=ghp_your_token_here

# 3. Analyze and create issues automatically!
repocheck analyze your-username/your-repo --issue

Result: Multiple GitHub issues created with detailed analysis, impact assessment, and fix instructions! 🎉

🔑 Setting up GitHub Token

For the --issue feature, you'll need a GitHub Personal Access Token with specific permissions:

1. Go to github.com/settings/tokens
2. Generate a new "Tokens (classic)"
3. Select these scopes:
   • repo (full repository access) OR the following granular permissions:
     • metadata — Read repository metadata
     • contents — Read repository contents
     • issues — Create and manage issues
4. Copy the token (starts with ghp_)

Important

📖 Complete setup guide with screenshots

---

🧭 Issue Publishing TL;DR

--issue (CLI) and Publish to GitHub Issues (Web UI) both need GitHub API credentials with issue-write permission.

CLI

export GITHUB_TOKEN=ghp_your_pat_here
repocheck analyze owner/repo --issue

Web UI

npm run dev:local-ui

In the form:

1. Enable Publish to GitHub Issues
2. Optional: paste GitHub Token (overrides server env token)
3. Run analysis

If no token is provided in the field, the backend uses GITHUB_TOKEN from the server environment.

For full step-by-step setup and 401/403 troubleshooting, see docs/issue-publishing.md.

---

Category	What's Checked	Example Findings
📚 Docs & Onboarding	README, setup instructions, contributing guidelines	Missing installation steps
⚡ Developer Experience	Build scripts, language version, project structure	No .nvmrc or .node-version
🔄 CI/CD	GitHub Actions, test automation, build pipelines	No CI workflow found
🧪 Quality & Tests	Test framework, linting, formatting, coverage	Missing test configuration
📋 Governance	LICENSE, CODE_OF_CONDUCT, SECURITY policy	No LICENSE file
🔐 Security	Dependabot/Renovate, security policy, secret scanning	No dependency updates configured

---

🚀 Quick Start

Prerequisites

Important

• GitHub Copilot — Active subscription required
• Node.js — Version 18.0.0 or higher

Installation

# Clone the repository
git clone https://github.com/glaucia86/repocheckai.git
cd repocheckai

# Install dependencies and build
npm install
npm run build

# Link globally
npm link

Usage

# Interactive mode
repocheck

# Direct analysis
repocheck vercel/next.js

# Deep analysis with premium model
repocheck vercel/next.js --model claude-sonnet-4 --deep

# 🚀 Auto-create GitHub issues for each problem found
repocheck vercel/next.js --issue

Note

--issue requires a GitHub token. Learn how to set it up.

---

🔧 How It Works

---

📖 Commands

Command	Description
/analyze <repo>	Quick analysis via GitHub API
/deep <repo>	Deep analysis with full source scan
/copy	Copy last report to clipboard
/export [path]	Save report as markdown file
/model [name]	Switch AI model (now works in onboarding phase)
/help	Show all available commands
/quit	Exit RepoCheckAI

Tip

Use /deep for comprehensive code quality analysis. Use /analyze for quick governance checks.

🗂️ Repository Layout

The repository keeps application runtime code in src/ and the public website in site/:

site/          # Static marketing/docs site deployed to GitHub Pages
src/           # Clean architecture runtime code

Implementation source is now organized by clean architecture layers in src/:

• Presentation: src/presentation/** (CLI, API, Web UI, terminal UI)
• Application: src/application/** (analysis and reporting orchestration)
• Infrastructure: src/infrastructure/** (GitHub/providers/tools adapters)
• Domain: src/domain/** (schemas, contracts, interfaces)
• Shared utilities: src/utils/**

🖥️ Local Web UI

The project has a single Web UI implementation served from src/presentation/web/public by src/presentation/web/main.ts.

npm run dev:web-ui:api
npm run dev:web-ui

Or run both services together:

npm run dev:local-ui

Current MVP capabilities:

• Create analysis jobs from web state/client modules
• Read completed markdown/JSON reports
• Stream progress seeds and cancel running jobs
• Copy and export completed reports (md and json)

---

📝 Examples

Quick Analysis

repocheck
/analyze microsoft/vscode

Deep Analysis with Custom Model

repocheck
/model claude-sonnet-4
/deep facebook/react

Export Report

repocheck
/analyze vercel/next.js
/export nextjs-report.md

Interactive Mode

repocheck
# Then use commands interactively
/analyze myorg/myrepo
/copy

---

🤖 Available AI Models

Model	Type	Best For
gpt-4o	Free	Balanced performance (default)
gpt-4.1	Free	Fast analysis
gpt-5.4	Premium ⚡	Latest GPT capabilities
gpt-5.3-codex	Premium ⚡	Advanced coding tasks
claude-sonnet-4	Premium ⚡	Detailed analysis
claude-opus-4.5	Premium ⚡	Most capable (3x rate limit)
o3	Premium ⚡	Deep reasoning tasks

Note

Premium models require GitHub Copilot Pro/Enterprise. See AI Models Guide for full list.

---

📚 Documentation

Document	Description
� Getting Started	Installation and first analysis
📖 User Guide	Complete usage guide with examples
💻 Commands	Full CLI command reference
📊 Analysis Categories	What gets analyzed in each category
🤖 AI Models	Available models and recommendations
🏗️ Architecture	Technical architecture and design
❓ FAQ	Frequently asked questions
🔧 Troubleshooting	Common issues and solutions
🤝 Contributing	How to contribute to RepoCheckAI

📖 Full documentation: docs/index.md

---

🏗️ Tech Stack

Copilot SDK AI Orchestration

Octokit GitHub API

Repomix Repo Packing

TypeScript Language

Zod Validation

🔧 Modular Architecture

The codebase follows SOLID principles for maintainability:

src/
├── cli/          # Command handlers, state, parsers
├── core/agent/   # Copilot SDK session, modular prompts
├── tools/        # Individual tool files (SRP)
├── ui/display/   # Display modules (spinner, menus, etc.)
└── types/        # Zod schemas, interfaces

Key Design Decisions:

• Agentic CLI: Uses GitHub Copilot SDK for AI-powered analysis
• Modular Prompts: System prompts composed from reusable base modules
• Tool-Based Architecture: AI agent invokes specific tools for data gathering
• Streaming Output: Real-time analysis with event-driven updates
• Security First: Content sanitization prevents prompt injection

📖 See Architecture Documentation for technical details.

---

⭐ Support This Project

If you find RepoCheckAI useful:

⭐ Star this repository	🐛 Report issues you encounter
💡 Suggest new features	🔀 Contribute via pull requests

---

📈 Star History

---

📄 License

MIT © Glaucia Lemos

---

👩‍💻 Author

Glaucia Lemos
_{A.I Developer at Zup Innovation/Itaú}



🐦 Twitter • 💼 LinkedIn • 🐙 GitHub

---

Made with 💚 using the GitHub Copilot SDK

⬆️ Back to Top