{"id":47640542,"url":"https://github.com/urmzd/github-insights","last_synced_at":"2026-04-06T05:01:48.764Z","repository":{"id":337344464,"uuid":"1153189366","full_name":"urmzd/github-insights","owner":"urmzd","description":"GitHub Action that generates SVG visualizations of your GitHub profile metrics","archived":false,"fork":false,"pushed_at":"2026-04-02T03:14:46.000Z","size":7914,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T08:49:27.605Z","etag":null,"topics":["github-action","github-metrics","github-profile","readme-stats"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urmzd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-09T02:25:34.000Z","updated_at":"2026-04-01T17:02:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/urmzd/github-insights","commit_stats":null,"previous_names":["urmzd/github-metrics"],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/urmzd/github-insights","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fgithub-insights","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fgithub-insights/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fgithub-insights/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fgithub-insights/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urmzd","download_url":"https://codeload.github.com/urmzd/github-insights/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Fgithub-insights/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31457726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T21:22:52.476Z","status":"online","status_checked_at":"2026-04-06T02:00:07.287Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github-action","github-metrics","github-profile","readme-stats"],"created_at":"2026-04-02T00:50:54.953Z","updated_at":"2026-04-06T05:01:48.755Z","avatar_url":"https://github.com/urmzd.png","language":"JavaScript","readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eGitHub Insights\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    Generate beautiful SVG insights visualizations for your GitHub profile README.\n    \u003cbr /\u003e\u003cbr /\u003e\n    \u003ca href=\"https://github.com/urmzd/github-insights/releases\"\u003eInstall\u003c/a\u003e\n    \u0026middot;\n    \u003ca href=\"https://github.com/urmzd/github-insights/issues\"\u003eReport Bug\u003c/a\u003e\n    \u0026middot;\n    \u003ca href=\"https://github.com/urmzd\"\u003eProfile Demo\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/urmzd/github-insights/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/urmzd/github-insights/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/urmzd/github-insights/actions/workflows/release.yml\"\u003e\u003cimg src=\"https://github.com/urmzd/github-insights/actions/workflows/release.yml/badge.svg\" alt=\"Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/urmzd/github-insights/issues\"\u003e\u003cimg src=\"https://img.shields.io/github/issues/urmzd/github-insights\" alt=\"Issues\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/urmzd/github-insights/pulls\"\u003e\u003cimg src=\"https://img.shields.io/github/issues-pr/urmzd/github-insights\" alt=\"Pull Requests\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/urmzd/github-insights/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/urmzd/github-insights\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@urmzd/github-insights\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@urmzd/github-insights\" alt=\"npm version\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Showcase\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" align=\"center\"\u003e\u003cstrong\u003eSVG Output\u003c/strong\u003e\u003c/td\u003e\n\u003ctd width=\"50%\" align=\"center\"\u003e\u003cstrong\u003eCLI / TUI\u003c/strong\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"assets/insights/index.svg\" alt=\"Example SVG output\"\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"showcase/demo.gif\" alt=\"GitHub Insights TUI demo\"\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nRun `github-insights generate` locally for a full TUI experience with live phase tracking, spinners, and timing for each pipeline step.\n\n## Features\n\n- **Composable sections** — pick and order sections (`spotlight`, `velocity`, `rhythm`, `constellation`, `portfolio`, `impact`) or use a preset\n- **Spotlight** — surfaces your top projects ranked by AI analysis (activity, relevance, impact)\n- **Language Velocity** — streamgraph showing how your language usage has evolved over the past year\n- **Contribution Rhythm** — radar chart revealing day-of-week commit patterns, plus stats (commits, PRs, reviews, streak)\n- **Project Constellation** — visual map of projects positioned by language ecosystem and complexity, with connections between related repos\n- **Portfolio** — full project list in a collapsible `\u003cdetails\u003e` tag, grouped by AI-classified category\n- **Open Source Impact** — external contributions sorted by repo star count with logarithmic impact bars\n- **AI preamble generation** — auto-generated profile introduction (or supply your own `PREAMBLE.md`)\n- **AI project classification** — repos classified by status (active/maintained/inactive) and purpose (Developer Tools/SDKs/Applications/Research)\n- **CLI / TUI** — local generation with an interactive terminal UI (Ink-based), live progress, and phase timing; powered by [Commander](https://www.npmjs.com/package/commander) with `init` and `generate` subcommands\n- **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\n- **Config validation** — `github-insights.yml` (or `.yaml` / `.toml`) validated with [Zod](https://www.npmjs.com/package/zod); invalid values are silently ignored with sensible defaults\n- **Exclude archived repos** — archived repositories are excluded from the portfolio by default (`exclude_archived: true`)\n- **Social badges** — auto-detected from your GitHub profile (website, Twitter, LinkedIn, etc.)\n- **Dual theme** — SVGs automatically adapt to GitHub's light and dark mode via `prefers-color-scheme`\n- **CSS animations** — subtle fade-in and scale animations on load\n- **Configuration** — customize name, title, bio, sections, and more via `github-insights.yml`; scaffold with `github-insights init`\n\n## Quick Start\n\n### Install\n\n```sh\n# One-line install\ncurl -fsSL https://raw.githubusercontent.com/urmzd/github-insights/main/install.sh | bash\n\n# Or via npm\nnpm install -g @urmzd/github-insights\n\n# Or run without installing\nnpx @urmzd/github-insights --help\n```\n\n### CLI Usage\n\n```sh\n# Authenticate with GitHub (required)\ngh auth login\n\n# Scaffold a config file in your profile repo\ngithub-insights init\n\n# Generate metrics (launches interactive TUI)\ngithub-insights generate\n```\n\nThe CLI reads your `gh` auth token via `$GITHUB_TOKEN`. Pass options explicitly if needed:\n\n```sh\ngithub-insights generate \\\n  --token \"$(gh auth token)\" \\\n  --username your-username \\\n  --output-dir assets/insights \\\n  --template showcase\n```\n\n#### Commands\n\n| Command | Description |\n|---------|-------------|\n| `github-insights init` | Create a `github-insights.yml` config file with defaults |\n| `github-insights generate` (default) | Generate metrics and visualizations |\n\n#### Options (`generate`)\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `-t, --token \u003ctoken\u003e` | GitHub token | `$GITHUB_TOKEN` |\n| `-u, --username \u003cusername\u003e` | GitHub username | `$GITHUB_REPOSITORY_OWNER` |\n| `-o, --output-dir \u003cdir\u003e` | Output directory for SVGs | `assets/insights` |\n| `--readme-path \u003cpath\u003e` | README output path (`none` to skip) | `none` (local) / `README.md` (CI) |\n| `--template \u003cname\u003e` | Template preset | `showcase` |\n| `--sections \u003clist\u003e` | Comma-separated section list (overrides template) | |\n| `--fail-fast` | Exit with error instead of falling back to heuristics when AI is unavailable | `false` |\n\n### GitHub Action (CI)\n\nCreate `.github/workflows/metrics.yml` in your profile repository (`\u003cusername\u003e/\u003cusername\u003e`):\n\n```yaml\nname: Metrics\non:\n  schedule:\n    - cron: \"0 0 * * *\" # daily\n  workflow_dispatch:\n\npermissions:\n  contents: write\n  models: read\n\njobs:\n  generate:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: urmzd/github-insights@main\n        with:\n          github-token: ${{ secrets.GITHUB_TOKEN }}\n```\n\nThe action commits updated SVGs and a generated `README.md` to your repo automatically.\n\n\u003e **Branch protection?** The default `GITHUB_TOKEN` cannot push to branches with protection rules. Use a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) or a [GitHub App](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps) token instead — pass it as `github-token: ${{ secrets.YOUR_PAT }}`.\n\n#### Action Inputs\n\n| Input | Description | Default |\n|-------|-------------|---------|\n| `github-token` | GitHub token (needs `repo` read + `models:read` for AI) | `${{ github.token }}` |\n| `template` | Section preset (`classic`, `modern`, `minimal`, `ecosystem`, `showcase`) | `showcase` |\n| `sections` | Comma-separated ordered list of sections (overrides `template`) | _(empty — uses template)_ |\n| `config-file` | Path to config file (also accepts `.yaml` / `.toml`) | `github-insights.yml` |\n| `username` | GitHub username to generate metrics for | `${{ github.repository_owner }}` |\n| `output-dir` | Directory to write SVG files to | `assets/insights` |\n| `readme-path` | Output path for the generated profile README (set to `none` to skip) | `README.md` |\n| `commit-push` | Whether to commit and push generated files | `true` |\n| `commit-message` | Commit message for generated files | `chore: update metrics` |\n| `commit-name` | Git user name for commits | `github-actions[bot]` |\n| `commit-email` | Git user email for commits | `41898282+github-actions[bot]@users.noreply.github.com` |\n| `fail-fast` | Exit with error instead of falling back to heuristics when AI is unavailable | `false` |\n\n## Configuration\n\nCreate `github-insights.yml` (or `.yaml` / `.toml`) in your repo root, or run `github-insights init` to scaffold one:\n\n```yaml\nname: Your Name\npronunciation: your-name\ntitle: Software Engineer\ndesired_title: Senior Software Engineer\nbio: Building things on the internet.\npreamble: PREAMBLE.md      # path to custom preamble (optional)\ntemplate: showcase          # section preset (optional)\nexclude_archived: true      # exclude archived repos from portfolio (default: true)\nfail_fast: false            # fail instead of falling back to heuristics (default: false)\nsections:                   # explicit section order (overrides template)\n  - spotlight\n  - velocity\n  - rhythm\n  - constellation\n  - portfolio\n  - impact\n\n# AI prompt valves — override model, temperature, or prompt text per task.\n# Values can be inline strings or paths to .txt/.md files.\nai:\n  preamble:\n    model: gpt-4.1           # GitHub Models model ID\n    temperature: 0.5\n    system: prompts/preamble-system.txt\n    user: prompts/preamble-user.txt\n  classification:\n    model: gpt-4.1\n    temperature: 0.15\n    system: prompts/classification-system.txt\n    user: prompts/classification-user.txt\n```\n\nAll fields are optional and validated with Zod — invalid values are silently ignored with sensible defaults. The full schema is defined in `src/config.ts`.\n\n## AI Features\n\n### Preamble Generation\n\nWhen 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.\n\nTo 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`.\n\n### Project Classification\n\nThe action uses GitHub Models (default: `gpt-4.1`) to classify repositories by maintenance status (active/maintained/inactive) and purpose category (Developer Tools, SDKs, Applications, Research \u0026 Experiments), with AI-generated summaries for each project. The AI also ranks spotlight candidates.\n\n### Customizing AI Prompts\n\nYou can override the model, temperature, system prompt, and user prompt for both AI tasks via the `ai:` block in `github-insights.yml`:\n\n```yaml\nai:\n  preamble:\n    model: gpt-4.1        # any GitHub Models model ID\n    temperature: 0.5\n    system: prompts/my-system-prompt.txt   # file path or inline string\n    user: prompts/my-user-prompt.txt\n  classification:\n    model: gpt-4.1\n    temperature: 0.15\n    system: \"You are a project classifier.\"  # inline string\n    user: prompts/classification-user.txt\n```\n\nPrompt 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.\n\n### Token Permissions\n\nFor AI features, your workflow needs:\n\n```yaml\npermissions:\n  contents: write  # to commit generated files\n  models: read     # for AI project classification and preamble generation\n```\n\n### Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | General error |\n| 2 | Rate limited (AI API) |\n| 3 | AI unavailable (network, bad response, empty output) |\n| 4 | Authentication failed (invalid or insufficient token permissions) |\n| 5 | API error |\n\nBy 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.\n\n## Sections\n\nThe generated README is composed from configurable sections. Control which sections appear and in what order via `github-insights.yml` or the `sections` action input:\n\n| Section | Type | Description |\n|---------|------|-------------|\n| `spotlight` | text | Top projects ranked by AI analysis (activity, relevance, impact) |\n| `velocity` | svg | Language Velocity streamgraph |\n| `rhythm` | svg | Contribution Rhythm radar chart |\n| `constellation` | svg | Project Constellation map |\n| `portfolio` | text | Full project list in a collapsible `\u003cdetails\u003e` tag, grouped by category |\n| `impact` | svg | Open Source Impact trail |\n\n**Default** (all sections):\n```yaml\nsections:\n  - spotlight\n  - velocity\n  - rhythm\n  - constellation\n  - portfolio\n  - impact\n```\n\n**Minimal example** (just stats):\n```yaml\nsections:\n  - velocity\n  - rhythm\n```\n\nOr via the action input:\n```yaml\n- uses: urmzd/github-insights@main\n  with:\n    sections: spotlight,velocity,rhythm\n```\n\n### Spotlight Ranking\n\nThe 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\".\n\n### Template Presets\n\nThe `template` input maps to predefined section lists:\n\n| Preset | Sections |\n|--------|----------|\n| `showcase` (default) | `spotlight, velocity, rhythm, constellation, portfolio, impact` |\n| `ecosystem` | `spotlight, velocity, rhythm, constellation, portfolio, impact` |\n| `modern` | `spotlight, velocity, rhythm, constellation, impact` |\n| `classic` | `velocity, rhythm, constellation, impact` |\n| `minimal` | `velocity, rhythm` |\n\nThe `sections` input overrides `template` when both are specified.\n\n## Local Development\n\n### Prerequisites\n\n- Node.js 24+\n- `gh` CLI (authenticated) for local generation\n\n### Commands\n\n```sh\nnpm run ci          # full CI check (fmt, lint, typecheck, test, build)\nnpm run generate    # generate metrics locally via tsx (dev mode)\nnpm run build       # build action + CLI bundles (dist/ and dist-cli/)\nnpm run showcase    # record a terminal demo GIF via teasr\nnpm test            # run tests\nnpm run typecheck   # type-check\nnpm run lint        # lint\nnpm run fmt         # format check\nnpm run fmt:fix     # format fix\n```\n\n\u003e **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 preview is generated at `examples/default/README.md`.\n\n## Output Files\n\n| File | Description |\n|------|-------------|\n| `assets/insights/index.svg` | Combined visualization with all sections |\n| `assets/insights/metrics-velocity.svg` | Language Velocity streamgraph |\n| `assets/insights/metrics-rhythm.svg` | Contribution Rhythm radar + stats |\n| `assets/insights/metrics-constellation.svg` | Project Constellation map |\n| `assets/insights/metrics-impact.svg` | Open Source Impact trail |\n| `README.md` | Generated profile README (CI only) |\n| `examples/default/README.md` | Local preview (generated when `--readme-path` is not `none`) |\n| `showcase/demo.gif` | Terminal demo recording (generated by `npm run showcase`) |\n\n## Agent Skill\n\nThis project ships an [Agent Skill](https://github.com/vercel-labs/skills) for use with Claude Code, Cursor, and other compatible agents.\n\nAvailable as portable agent skills in [`skills/`](skills/).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furmzd%2Fgithub-insights","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furmzd%2Fgithub-insights","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furmzd%2Fgithub-insights/lists"}