gh-toolkit

GitHub repository portfolio management and presentation toolkit with LLM-powered categorization and beautiful site generation

A comprehensive command-line tool for managing GitHub repository portfolios at scale. Perfect for academics, educators, and developers who need to organize, categorize, and showcase their GitHub repositories professionally.

✨ Features

📋 Repository Management - List, filter, and extract comprehensive repository data
🤖 LLM-Powered Categorization - Intelligent repository classification using Claude AI
📝 Description Generation - AI-powered repository description creation
🏷️ Automated Topic Tagging - Smart topic suggestions with custom tag preferences
🔖 Topic Badges - Generate shields.io badges from repository topics
🩺 Repository Health Checking - Comprehensive quality audits with best practices compliance
🎨 Portfolio Site Generation - Beautiful, responsive HTML portfolios with 4 themes
📄 Landing Page Generation - Convert README.md to stunning HTML or Jekyll pages
📧 Invitation Management - Bulk accept/leave repository collaborations
🏢 Organization READMEs - Generate and push org profile READMEs directly to GitHub
🎯 Academic Workflow - Perfect alternative to GitHub Classroom
🖥️ Interactive TUI - Full-featured terminal UI for visual repository management
⚡ Modern CLI - Built with typer and rich for beautiful terminal experience

gh-toolkit vs GitHub CLI (`gh`)

gh-toolkit complements the official GitHub CLI (gh) rather than replacing it.

Use `gh` for	Use `gh-toolkit` for
Pull requests & issues	Portfolio site generation
GitHub Actions workflows	Bulk repository operations
Releases & gists	AI-powered categorization
Codespaces & projects	Repository health auditing
Single-repo operations	Cross-org portfolio management
Raw API access	Academic/educator workflows

They work great together:

# Daily work with gh
gh pr create --fill && gh run watch

# Portfolio presentation with gh-toolkit
gh-toolkit repo extract my-repos.txt --output data.json
gh-toolkit site generate data.json --theme resume

See docs/gh-cli-comparison.md for a detailed feature comparison.

Working with local clones instead? gh-toolkit manages your repos on GitHub. For the checkouts on your disk, two focused tools pair well with it: gita for multi-repo status and batch git commands across many clones, and git-reclaim — a tiny, zero-dependency git reclaim subcommand that frees disk space (purge regenerable caches, git gc) and flags clones that are safe to delete because the remote already has everything.

🚀 Quick Start

Installation

pip install gh-toolkit

Authentication

Most commands need a GitHub token. gh-toolkit resolves one from the first available source, so if you already use the gh CLI there's nothing to set up:

The --token flag (visible in shell history/process lists — prefer the others)
The GITHUB_TOKEN environment variable
A token key in the config file (see below)
The gh CLI's stored token (gh auth token)

Configuration file (optional)

Put repeated defaults in gh-toolkit.toml (project-local, takes precedence) or ~/.config/gh-toolkit/config.toml:

token = "ghp_..."        # optional — env var or gh CLI usually better

Basic Usage

# List repositories
gh-toolkit repo list username

# Extract repository data with LLM categorization
gh-toolkit repo extract repos.txt --anthropic-key=sk-...

# Generate beautiful portfolio site
gh-toolkit site generate repos_data.json --theme educational

# Convert README to landing page
gh-toolkit page generate README.md --output index.html

# Check repository health and best practices
gh-toolkit repo health username/repo --rules academic

# Add topic tags to repositories
gh-toolkit repo tag username/* --dry-run

# Manage invitations (perfect for educators)
gh-toolkit invite accept --dry-run

📖 Commands

Repository Commands

# List repositories with filters
gh-toolkit repo list michael-borck --public --language Python

# Machine-readable output for piping (jq, spreadsheets, gradebooks)
gh-toolkit repo list michael-borck --json | jq '.[].name'

# Extract comprehensive data (concurrent; --resume continues an interrupted run)
gh-toolkit repo extract repos.txt \
  --anthropic-key=sk-... \
  --parallel 8 \
  --output portfolio_data.json
gh-toolkit repo extract repos.txt --resume --output portfolio_data.json

# Generate repository descriptions with AI
gh-toolkit repo describe "user/*" --dry-run
gh-toolkit repo describe user/repo --model claude-sonnet-4-6

# Add intelligent topic tags
gh-toolkit repo tag user/repo --force --anthropic-key=sk-...
gh-toolkit repo tag "user/*" --tags "edtech: Educational, tool: CLI tools"

# Generate topic badges for READMEs
gh-toolkit repo badges user/repo
gh-toolkit repo badges "user/*" --apply  # Auto-update READMEs

# Check repository health and compliance
gh-toolkit repo health user/repo --rules professional --min-score 80
gh-toolkit repo health "user/*" --json | jq '.[] | {repo: .repository, grade}'

# Custom rubric: re-weight checks, set grade thresholds, mark checks required
gh-toolkit repo health user/repo --rubric example_rubric.yaml

# Post the health report back as a GitHub issue (idempotent; confirms first)
gh-toolkit repo health "org/*" --post-issue

# Roster submission report (joins health to a class roster CSV)
gh-toolkit repo roster students.csv --org cs101 --repo-pattern "lab1-{github}"

# Clone repos; --before snapshots each at the last commit before a deadline
gh-toolkit repo clone student_repos.txt --target-dir ./submissions
gh-toolkit repo clone student_repos.txt --before "2026-06-12 23:59"

Site Generation

# Generate portfolio with different themes
gh-toolkit site generate repos.json --theme educational
gh-toolkit site generate repos.json --theme resume  
gh-toolkit site generate repos.json --theme research
gh-toolkit site generate repos.json --theme portfolio

# Custom title and metadata
gh-toolkit site generate repos.json \
  --title "My Projects" \
  --description "My awesome software" \
  --metadata custom.yaml

Page Generation

# Generate standalone HTML landing page
gh-toolkit page generate README.md

# Generate Jekyll-compatible markdown
gh-toolkit page generate README.md --jekyll --output index.md

# Custom title and description
gh-toolkit page generate README.md --jekyll \
  --title "My Project" \
  --description "Amazing software project"

Organization Commands

# Generate README for an organization
gh-toolkit org readme my-org --template detailed

# Push README directly to organization's GitHub profile
gh-toolkit org readme my-org --apply

# Generate with filtering
gh-toolkit org readme my-org --max-repos 20 --min-stars 5 --apply

Portfolio Commands

# Generate cross-organization portfolio
gh-toolkit portfolio generate --discover
gh-toolkit portfolio generate --org org1 --org org2 --html portfolio.html

# Audit repositories for missing metadata
gh-toolkit portfolio audit --discover
gh-toolkit portfolio audit --user --output audit-report.json

# Fix what the audit finds: generate missing descriptions/topics in place
gh-toolkit portfolio audit --org my-org --fix --dry-run   # preview first
gh-toolkit portfolio audit --org my-org --fix --license mit

Invitation Management

# Accept all pending invitations
gh-toolkit invite accept --dry-run

# Leave repositories you're collaborating on
gh-toolkit invite leave --confirm

🖥️ Terminal UI (TUI)

gh-toolkit includes a full-featured terminal user interface for visual repository management.

Installation

# Install with TUI support
pip install gh-toolkit[tui]

Launch

gh-toolkit tui

Features

Browse Organizations - Navigate your GitHub organizations visually
Search & Filter - Press / to search repos by name or description
Multi-Select - Use Space to select multiple repos, Ctrl+A to select all
Bulk Actions - Press a to open the action modal for selected repos
Context-Aware - Actions apply to selected items or all visible items

Keybindings

Key	Action
`?`	Show help
`a`	Open actions menu
`/`	Search/filter
`Space`	Toggle selection
`Ctrl+A`	Select all
`Ctrl+D`	Deselect all
`Enter`	View/drill down
`Esc`	Back/cancel
`s`	Cycle sort (in org view)
`g`	Generate README (in org view)

Actions Menu

The TUI provides form-based action selection:

Generate Descriptions - AI-powered descriptions with model selection
Add Topics - Intelligent tagging with preferred tag support
Generate Badges - Create shields.io badges with style options
Health Check - Audit repository quality
Audit - Find missing metadata

All actions support dry-run mode for safe previewing.

🎨 Portfolio Themes

Educational Theme

Perfect for educators and academic portfolios

Purple gradient design
Emphasizes learning resources and tools
Category order: Desktop → Web → Python → Learning Resources

Resume Theme

Professional showcase for career portfolios

Blue corporate design
Highlights technical expertise
Category order: Web → Desktop → Python → Infrastructure

Research Theme

Academic research and scientific computing

Green academic design
Focuses on publications and analysis
Category order: Learning → Analysis → Python → Web

Portfolio Theme

General project showcase

Indigo modern design
Balanced category presentation
Category order: Web → Desktop → Python → Infrastructure

🤖 LLM Integration

gh-toolkit integrates with Anthropic's Claude for intelligent repository analysis:

Smart Categorization - Analyzes README, description, languages, and topics
Confidence Scoring - Shows certainty of AI classifications
Graceful Fallback - Uses rule-based classification when LLM unavailable
Topic Generation - Suggests relevant GitHub topics based on content

export ANTHROPIC_API_KEY=sk-ant-...
gh-toolkit repo extract repos.txt  # Uses LLM automatically

📚 Academic Use Case

Perfect alternative to GitHub Classroom:

# Students accept repository invitations
gh-toolkit invite accept

# Track submissions against a class roster (CSV with a github username column).
# Reports who set up their repo and its hygiene score — not a mark of the work.
gh-toolkit repo roster students.csv --org cs101 --repo-pattern "lab1-{github}"
gh-toolkit repo roster students.csv --org cs101 --output submissions.csv

# Snapshot every submission at the deadline (last commit before the due date),
# producing an owner/repo folder tree ready for content-assessment tools.
gh-toolkit repo clone student_repos.txt --before "2026-06-12 23:59" \
  --target-dir ./submissions

# Extract all student repositories  
gh-toolkit repo extract student_repos.txt --anthropic-key=sk-...

# Generate class portfolio site
gh-toolkit site generate student_data.json \
  --theme educational \
  --title "CS 101 Student Projects" \
  --output class_portfolio.html

The roster CSV needs a GitHub username column (github, username, handle, …); name, student_id, and an explicit repo column are optional and auto-detected. Each student's repo is resolved from an explicit repo column, the --repo-pattern (fields: {github}, {username}, {id}, {name}), or org/<username>. See example_roster.csv. This is the GitHub-side companion to content-assessment tools — it tracks whether the repo was submitted and set up well, leaving marking of the work to a human (see docs/ROADMAP.md).

🛠️ Development

Setup

git clone https://github.com/michael-borck/gh-toolkit.git
cd gh-toolkit
uv sync --group dev

Testing

# Run all tests
./scripts/test.sh

# Generate coverage report
./scripts/coverage.sh

# Run specific test suites
uv run pytest tests/unit/ -v
uv run pytest tests/integration/ -v

Architecture

src/gh_toolkit/
├── cli.py                 # Main CLI entry point
├── commands/              # Command implementations
│   ├── repo.py           # Repository management (list, extract, describe, badges, health)
│   ├── org.py            # Organization commands (readme)
│   ├── portfolio.py      # Portfolio commands (generate, audit)
│   ├── site.py           # Site generation
│   ├── tag.py            # Topic tagging
│   └── invite.py         # Invitation management
├── tui/                   # Terminal UI (optional)
│   ├── app.py            # Main TUI application
│   ├── screens/          # TUI screens (home, org, repo, help)
│   └── widgets/          # Reusable widgets (action modal, etc.)
└── core/                  # Core functionality
    ├── github_client.py   # GitHub API client
    ├── repo_extractor.py  # Data extraction
    ├── site_generator.py  # HTML generation
    ├── readme_generator.py # Organization README generation
    └── topic_tagger.py    # LLM tagging

🔧 Configuration

Environment Variables

export GITHUB_TOKEN=ghp_...          # GitHub personal access token
export ANTHROPIC_API_KEY=sk-ant-...  # Anthropic API key (optional)

GitHub Token Scopes

repo - Access repositories
read:org - Read organization membership
write:org - Accept organization invitations

📊 Example Workflow

# 1. Extract repository data
gh-toolkit repo extract my_repos.txt \
  --anthropic-key=$ANTHROPIC_API_KEY \
  --output extracted_data.json

# 2. Add topic tags
gh-toolkit repo tag my_repos.txt \
  --anthropic-key=$ANTHROPIC_API_KEY \
  --force

# 3. Generate portfolio site
gh-toolkit site generate extracted_data.json \
  --theme portfolio \
  --title "My Software Portfolio" \
  --output index.html

# 4. Deploy to GitHub Pages
# Upload index.html to your GitHub Pages repository

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with typer and rich
LLM integration powered by Anthropic Claude
Modern Python tooling with uv

⭐ Star this repository if gh-toolkit helps you manage your GitHub portfolio!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

gh-toolkit

✨ Features

gh-toolkit vs GitHub CLI (gh)

🚀 Quick Start

Installation

Authentication

Configuration file (optional)

Basic Usage

📖 Commands

Repository Commands

Site Generation

Page Generation

Organization Commands

Portfolio Commands

Invitation Management

🖥️ Terminal UI (TUI)

Installation

Launch

Features

Keybindings

Actions Menu

🎨 Portfolio Themes

Educational Theme

Resume Theme

Research Theme

Portfolio Theme

🤖 LLM Integration

📚 Academic Use Case

🛠️ Development

Setup

Testing

Architecture

🔧 Configuration

Environment Variables

GitHub Token Scopes

📊 Example Workflow

🤝 Contributing

📝 License

🙏 Acknowledgments

gh-toolkit vs GitHub CLI (`gh`)