Showcase

Run github-insights generate locally for a full TUI experience with live phase tracking, spinners, and timing for each pipeline step.

Contents

• Features
• Quick Start
• Configuration
• AI Features
• Sections
• Local Development
• Output Files
• Agent Skill
• License

Features

• Composable sections — pick and order sections (spotlight, velocity, rhythm, constellation, portfolio, impact) or use a preset
• Spotlight — surfaces your top projects ranked by AI analysis (activity, relevance, impact)
• Language Velocity — streamgraph showing how your language usage has evolved over the past year
• Contribution Rhythm — radar chart revealing day-of-week commit patterns, plus stats (commits, PRs, reviews, streak)
• Project Constellation — visual map of projects positioned by language ecosystem and complexity, with connections between related repos
• Portfolio — full project list in a collapsible <details> tag, grouped by AI-classified category
• Open Source Impact — external contributions sorted by repo star count with logarithmic impact bars
• AI preamble generation — auto-generated profile introduction (or supply your own PREAMBLE.md)
• AI project classification — repos classified by status (active/maintained/inactive) and purpose (Developer Tools/SDKs/Applications/Research)
• CLI / TUI — local generation with an interactive terminal UI (Ink-based), live progress, and phase timing; powered by Commander with init and generate subcommands
• Configurable AI prompts — override model, temperature, and prompt text per AI task via the ai: config block; prompts can be inline strings or paths to .txt/.md files
• Config validation — github-insights.yml (or .yaml / .toml) validated with Zod; invalid values are silently ignored with sensible defaults
• Exclude archived repos — archived repositories are excluded from the portfolio by default (exclude_archived: true)
• Social badges — auto-detected from your GitHub profile (website, Twitter, LinkedIn, etc.)
• Dual theme — SVGs automatically adapt to GitHub's light and dark mode via prefers-color-scheme
• CSS animations — subtle fade-in and scale animations on load
• Configuration — customize name, title, bio, sections, and more via github-insights.yml; scaffold with github-insights init

Quick Start

Install

# One-line install
curl -fsSL https://raw.githubusercontent.com/urmzd/github-insights/main/install.sh | sh

# Or via npm
npm install -g @urmzd/github-insights

# Or run without installing
npx @urmzd/github-insights --help

CLI Usage

# Authenticate with GitHub (required)
gh auth login

# Scaffold a config file in your profile repo
github-insights init

# Generate metrics (launches interactive TUI)
github-insights generate

The CLI reads your gh auth token via $GITHUB_TOKEN. Pass options explicitly if needed:

github-insights generate \
  --token "$(gh auth token)" \
  --username your-username \
  --output-dir assets/insights \
  --template showcase

Commands

| Command | Description | |---------|-------------| | github-insights init | Create a github-insights.yml config file with defaults | | github-insights generate (default) | Generate metrics and visualizations |

Options (generate)

| Option | Description | Default | |--------|-------------|---------| | -t, --token <token> | GitHub token | $GITHUB_TOKEN | | -u, --username <username> | GitHub username | $GITHUB_REPOSITORY_OWNER | | -o, --output-dir <dir> | Output directory for SVGs | assets/insights | | --config-file <path> | Config file path | $CONFIG_FILE | | --readme-path <path> | README output path (none to skip) | none (local) / README.md (CI) | | --examples-dir <dir> | Local preset gallery output (none to skip) | examples (local) / none (CI) | | --template <name> | Template preset | showcase | | --sections <list> | Comma-separated section list (overrides template) | | | --fail-fast | Exit with error instead of falling back to heuristics when AI is unavailable | false | | --no-cache | Recompute AI outputs instead of reusing unchanged cached results | cache enabled | | --format <format> | Output format (human or json; json exports section data) | human |

GitHub Action (CI)

Create .github/workflows/metrics.yml in your profile repository (<username>/<username>):

name: Metrics
on:
  schedule:
    - cron: "0 0 * * *" # daily
  workflow_dispatch:

permissions:
  contents: write
  models: read

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: urmzd/github-insights@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

The action commits updated SVGs and a generated README.md to your repo automatically.

Branch protection? The default GITHUB_TOKEN cannot push to branches with protection rules. Use a Personal Access Token or a GitHub App token instead — pass it as github-token: ${{ secrets.YOUR_PAT }}.

Action Inputs

| Input | Description | Default | |-------|-------------|---------| | github-token | GitHub token (needs repo read + models:read for AI) | ${{ github.token }} | | template | Section preset (classic, modern, minimal, ecosystem, showcase) | showcase | | sections | Comma-separated ordered list of sections (overrides template) | (empty — uses template) | | config-file | Path to config file (also accepts .yaml / .toml) | github-insights.yml | | username | GitHub username to generate metrics for | ${{ github.repository_owner }} | | output-dir | Directory to write SVG files to | assets/insights | | readme-path | Output path for the generated profile README (set to none to skip) | README.md | | commit-push | Whether to commit and push generated files | true | | commit-message | Commit message for generated files | chore: update metrics | | commit-name | Git user name for commits | github-actions[bot] | | commit-email | Git user email for commits | 41898282+github-actions[bot]@users.noreply.github.com | | fail-fast | Exit with error instead of falling back to heuristics when AI is unavailable | false | | export-json | Export section JSON data alongside SVGs | false | | cache | Reuse previous AI outputs when inputs are unchanged (stored in <output-dir>/.ai-cache.json) | true |

Configuration

Create github-insights.yml (or .yaml / .toml) in your repo root, or run github-insights init to scaffold one:

name: Your Name
pronunciation: your-name
title: Software Engineer
desired_title: Senior Software Engineer
bio: Building things on the internet.
preamble: PREAMBLE.md      # path to custom preamble (optional)
template: showcase          # section preset (optional)
exclude_archived: true      # exclude archived repos from portfolio (default: true)
fail_fast: false            # fail instead of falling back to heuristics (default: false)
cache: true                 # reuse AI outputs when inputs are unchanged (default: true)
sections:                   # explicit section order (overrides template)
  - spotlight
  - velocity
  - rhythm
  - constellation
  - portfolio
  - impact

# AI prompt valves — override model, temperature, or prompt text per task.
# Values can be inline strings or paths to .txt/.md files.
ai:
  preamble:
    model: openai/gpt-4.1    # GitHub Models model ID (publisher/model)
    temperature: 0.5
    system: prompts/preamble-system.txt
    user: prompts/preamble-user.txt
  classification:
    model: openai/gpt-4.1
    temperature: 0.15
    system: prompts/classification-system.txt
    user: prompts/classification-user.txt

All fields are optional and validated with Zod — invalid values are silently ignored with sensible defaults. The full schema is defined in src/config.ts.

AI Features

Preamble Generation

When no custom preamble is provided, the action uses AI to generate a profile introduction (max 50 words) drawn from your profile bio, title, top languages, and notable projects. It uses a professional but friendly tone.

To use your own text instead, create a PREAMBLE.md file in the repo root, or point to a custom file via the preamble field in github-insights.yml.

Project Classification

The action uses GitHub Models (default: openai/gpt-4.1) to classify repositories by maintenance status (active/maintained/inactive) and purpose category (Developer Tools, SDKs, Applications, Research & Experiments), with AI-generated summaries for each project. The AI also ranks spotlight candidates.

Customizing AI Prompts

You can override the model, temperature, system prompt, and user prompt for both AI tasks via the ai: block in github-insights.yml:

ai:
  preamble:
    model: openai/gpt-4.1 # any GitHub Models model ID
    temperature: 0.5
    system: prompts/my-system-prompt.txt   # file path or inline string
    user: prompts/my-user-prompt.txt
  classification:
    model: openai/gpt-4.1
    temperature: 0.15
    system: "You are a project classifier."  # inline string
    user: prompts/classification-user.txt

Prompt values that end in .txt or .md (or are absolute paths) are read from disk; all other values are used as inline prompt text. If a file path is specified but the file is not found, the built-in default prompt is used with a warning.

[!NOTE] Model availability depends on your Copilot plan. Without a paid Copilot plan, only low/high rate-limit-tier models (e.g. openai/gpt-4.1, meta/llama-4-maverick-17b-128e-instruct-fp8) are usable — custom-tier models such as openai/gpt-5 and openai/o3 return 400 Unavailable model. See the GitHub Models catalog and rate limits.

Token Permissions

For AI features, your workflow needs:

permissions:
  contents: write  # to commit generated files
  models: read     # for AI project classification and preamble generation

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Rate limited (AI API) | | 3 | AI unavailable (network, bad response, empty output) | | 4 | Authentication failed (invalid or insufficient token permissions) | | 5 | API error |

By default, AI failures are non-fatal — the pipeline falls back to heuristic classification and skips the AI preamble. Set fail-fast: true (action) or --fail-fast (CLI) to treat AI failures as errors with the appropriate exit code.

AI Output Caching

AI outputs (project classifications and the preamble) are cached in <output-dir>/.ai-cache.json, keyed by a hash of everything that feeds each model call — repo data, profile data, config, and prompt settings. When nothing changed since the last run, the cached output is reused and no model call is made. Since the cache file lives in the output directory, the action commits it alongside the SVGs, so scheduled CI runs skip AI calls on quiet days. Disable with cache: false (action or config) or --no-cache (CLI).

Sections

The generated README is composed from configurable sections. Control which sections appear and in what order via github-insights.yml or the sections action input:

| Section | Type | Description | |---------|------|-------------| | spotlight | text | Top projects ranked by AI analysis (activity, relevance, impact) | | velocity | svg | Language Velocity streamgraph | | rhythm | svg | Contribution Rhythm radar chart | | constellation | svg | Project Constellation map | | portfolio | text | Full project list in a collapsible <details> tag, grouped by category | | impact | svg | Open Source Impact trail |

Default (all sections):

sections:
  - spotlight
  - velocity
  - rhythm
  - constellation
  - portfolio
  - impact

Minimal example (just stats):

sections:
  - velocity
  - rhythm

Or via the action input:

- uses: urmzd/github-insights@main
  with:
    sections: spotlight,velocity,rhythm

Spotlight Ranking

The spotlight section surfaces your top projects using AI-based ranking. The LLM assigns a spotlight_rank to each repo during project classification, considering activity, relevance, and impact. Projects with recent commits (last 30 days) are labeled "Active"; those with commits in the last 90 days are labeled "Building".

Template Presets

The template input maps to predefined section lists:

| Preset | Sections | |--------|----------| | showcase (default) | spotlight, velocity, rhythm, constellation, portfolio, impact | | ecosystem | spotlight, velocity, rhythm, stack, portfolio, impact | | modern | spotlight, velocity, rhythm, constellation, impact | | classic | velocity, rhythm, constellation, impact | | minimal | velocity, rhythm |

The sections input overrides template when both are specified.

Local Development

Prerequisites

• Node.js 24+
• gh CLI (authenticated) for local generation

Commands

npm run ci          # full CI check (fmt, lint, typecheck, test, build)
npm run generate    # generate metrics locally via tsx (dev mode)
npm run build       # build action + CLI bundles (dist/ and dist-cli/)
npm run showcase    # record a terminal demo GIF via teasr
npm test            # run tests
npm run typecheck   # type-check
npm run lint        # lint
npm run fmt         # format check
npm run fmt:fix     # format fix

Note: When running locally (outside CI), commit-push defaults to false and readme-path defaults to none (skipped), so generation will not overwrite your project README or push commits. A preset gallery is generated at examples/README.md by default. Set --examples-dir none to skip it.

To preview this action against a nearby profile repo:

github-insights generate \
  --username urmzd \
  --config-file ../urmzd/github-insights.yml \
  --output-dir assets/insights \
  --examples-dir examples \
  --readme-path none

Output Files

| File | Description | |------|-------------| | assets/insights/index.svg | Combined visualization with all sections | | assets/insights/metrics-velocity.svg | Language Velocity streamgraph | | assets/insights/metrics-rhythm.svg | Contribution Rhythm radar + stats | | assets/insights/metrics-constellation.svg | Project Constellation map | | assets/insights/metrics-impact.svg | Open Source Impact trail | | assets/insights/metrics-stack.svg | Tech Stack layer map (when stack is included) | | assets/insights/.ai-cache.json | Cached AI classifications and preambles for unchanged inputs | | README.md | Generated profile README (CI only) | | examples/README.md | Local gallery showing each template preset | | examples/{showcase,ecosystem,modern,classic,minimal}/README.md | Per-preset local README previews | | showcase/demo.gif | Terminal demo recording (generated by npm run showcase) |

Agent Skill

This repo's conventions are available as portable agent skills in skills/.

License

Apache-2.0