Repo Optics - A developer hygiene analytics platform for Product Managers and Technical Leads.
repOptics scans GitHub repositories for decision evidence, architecture documentation, and delivery hygiene. It answers the question: "Do we have our house in order?"
Scans any public GitHub repository and scores it across 5 categories:
- Decisions: Architecture Decision Records (ADRs) and decision documentation
- Architecture: README quality, diagrams, and technical documentation
- Governance: CODEOWNERS, LICENSE, CONTRIBUTING.md, GOVERNANCE.md
- Delivery: CI/CD workflows, PR templates, and merge velocity metrics
- Dependencies: Package freshness audit (major/minor/patch updates)
A 5-step wizard to scaffold new projects with excellent hygiene from day one:
- Identity - Project name and description
- Codebase - TypeScript scaffolding and AI context (AGENTS.md)
- Governance - ADRs and ownership files
- Operations - CI/CD and Docker infrastructure
- Review & Download - Generate a ready-to-use ZIP
Visual Mermaid-based timeline showing ADR evolution and status changes over time.
Automated package.json analysis comparing installed versions against npm registry latest.
- Framework: Next.js 16 (App Router)
- React: React 19
- Language: TypeScript
- Styling: Tailwind CSS 4
- GitHub Integration: Octokit
- Visualizations: Mermaid.js
- ZIP Generation: JSZip (client-side)
- Testing: Vitest
# Install dependencies
npm install
# Run development server
npm run dev
# Run tests
npm test
# Build for production
npm run buildOpen http://localhost:3000 to use the app.
| Variable | Required | Description |
|---|---|---|
GITHUB_TOKEN |
Optional | Personal Access Token for higher rate limits and private repo access |
Without a token, repOptics uses unauthenticated GitHub API access (60 requests/hour limit).
- Navigate to the home page
- Enter a repository in
owner/repoformat (e.g.,facebook/react) - Click "Scan" to generate a hygiene report
- Click "Generate" or navigate to
/generate - Follow the 5-step wizard
- Download your configured starter kit ZIP
- Architecture Overview - System context and component diagrams
- Product Specification - Features and technical spec
- Architecture Decision Records - Documented decisions
- Contributing Guide - Development workflows
repOptics uses a "dry humor, developer nerd" persona. It doesn't just report findings; it gently comments on the state of your repo:
"Zero ADRs. Decisions made by hallway shouts?"
"No README. Good luck, future maintainers."
"Ship it. This repo is a shining example of engineering discipline."
See LICENSE for details.