DEV Community

Glaucia Lemos
Glaucia Lemos

Posted on

Repo Doctor - AI-powered GitHub Repository Health Analyzer

#githubchallenge #devchallenge #cli #githubcopilot

GitHub Copilot CLI Challenge Submission

This is a submission for the GitHub Copilot CLI Challenge

What I Built

Repo Doctor is an AI-powered CLI tool that acts as your repository's personal physician. It diagnoses GitHub repositories for health issues across 6 critical areas and prescribes actionable solutions.

🏥 The Problem

Every developer has inherited a codebase and wondered: "Is this repo healthy? What's missing? Where do I start?" Manually auditing a repository for best practices is tedious and easy to overlook.

💊 The Solution

Repo Doctor performs comprehensive health checks and delivers a diagnosis with:

  • 📊 Health Score — A 0-100% rating based on 6 categories
  • 🔍 Prioritized Findings — P0 (critical), P1 (high), P2 (suggestions)
  • 💡 Actionable Remediation — Specific fixes with code snippets
  • 🎯 Evidence-Based — Every finding backed by file evidence

6 Analysis Categories

Category What's Checked
📚 Docs & Onboarding README quality, setup instructions, contributing guide
⚡ Developer Experience Build scripts, lockfiles, project structure
🔄 CI/CD GitHub Actions, test automation, quality gates
🧪 Quality & Tests Test framework, linting, code coverage
📋 Governance LICENSE, CODE_OF_CONDUCT, SECURITY policy
🔐 Security Dependabot, secret scanning, security policy

Two Analysis Modes

  • 🔍 Quick Scan (/analyze) — Fast analysis via GitHub API (up to 20 file reads)
  • 🔬 Deep Analysis (/deep) — Full source code scan using Repomix for comprehensive review

Demo

🔗 GitHub Repository: github.com/glaucia86/repo-doctor

See it in Action

The CLI provides an interactive experience with:

  • Real-time streaming analysis
  • Slash commands (/analyze, /deep, /copy, /export)
  • Beautiful terminal UI with progress indicators
  • Prioritized findings with evidence and remediation steps

My Experience with GitHub Copilot CLI

Building with the GitHub Copilot SDK

Repo Doctor is built entirely with the GitHub Copilot SDK — the same AI agent runtime that powers Copilot CLI. This was my first deep dive into building an agentic CLI tool, and the experience was transformative.

How Copilot CLI Enhanced Development

1. Rapid Prototyping with Natural Language

Using Copilot CLI during development, I could quickly explore ideas:

$ copilot "How do I use defineTool() to create a custom tool that reads files from GitHub?"
Enter fullscreen mode Exit fullscreen mode

The AI provided working examples that I adapted for my repoTools.ts, saving hours of documentation reading.

2. Architecture Decisions

When designing the agent's system prompt, Copilot CLI helped me iterate on the analysis strategy:

$ copilot "What's the best way to structure a repository health check? 
           I want to analyze docs, CI/CD, tests, and security."
Enter fullscreen mode Exit fullscreen mode

This led to the 6-category framework with P0/P1/P2 prioritization.

3. Security Implementation

Copilot CLI was invaluable for implementing prompt injection protection:

$ copilot "How do I prevent prompt injection when the AI reads untrusted file content?"
Enter fullscreen mode Exit fullscreen mode

The suggestions led to my content sanitization layer that wraps all file content with delimiters and detects malicious patterns.

Key Technical Highlights

Custom Tools with defineTool():

const readRepoFile = defineTool("read_repo_file", {
  description: "Reads file content from repository with security sanitization",
  parameters: { /* ... */ },
  handler: async (args) => {
    const sanitized = sanitizeFileContent(rawContent, path);
    return { content: sanitized.content, securityFlags: sanitized.flags };
  },
});
Enter fullscreen mode Exit fullscreen mode

Streaming Session with Event Handling:

const session = await client.createSession({
  model: "claude-sonnet-4",
  streaming: true,
  tools: repoTools({ token }),
  systemMessage: { mode: "append", content: SYSTEM_PROMPT },
});

session.on((event) => {
  if (event.type === "assistant.message_delta") {
    process.stdout.write(event.data.deltaContent); // Real-time output
  }
});
Enter fullscreen mode Exit fullscreen mode

The Impact

Building Repo Doctor with GitHub Copilot CLI fundamentally changed how I approach CLI development:

  • 10x faster iteration — Natural language queries replaced stack overflow searches
  • Better architecture — AI suggestions led to cleaner patterns
  • Security by default — Copilot helped identify edge cases I would have missed
  • Joy of building — The interactive development loop made coding fun again

Tech Stack

  • GitHub Copilot SDK — AI agent orchestration
  • Octokit — GitHub API integration
  • Repomix — Repository packing for deep analysis
  • TypeScript — Type-safe development
  • Zod — Runtime validation
  • Chalk + Ora — Beautiful terminal UI

Repo Doctor is open source and available on GitHub. Give your repositories a health checkup! 🩺

Top comments (0)