🩺 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:

Go to github.com/settings/tokens
Generate a new "Tokens (classic)"
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
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:

Enable Publish to GitHub Issues
Optional: paste GitHub Token (overrides server env token)
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

alt text

📖 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.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

👩‍💻 Author

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

🐦 Twitter • 💼 LinkedIn • 🐙 GitHub

Made with 💚 using the GitHub Copilot SDK

⬆️ Back to Top

NAME

SYNOPSIS

INFO

DESCRIPTION

README