{"id":51164597,"url":"https://github.com/ayan-de/heatmap","last_synced_at":"2026-06-26T17:31:19.957Z","repository":{"id":363771870,"uuid":"1264733317","full_name":"ayan-de/heatmap","owner":"ayan-de","description":"Generate beautiful, customizable contribution heatmaps in your terminal with custom color themes, emoji cells, interactive      hover mode, and auto-detecting data keys.","archived":false,"fork":false,"pushed_at":"2026-06-10T08:30:45.000Z","size":18523,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T10:15:43.594Z","etag":null,"topics":["calender","cli","commander","github","heatmap","terminal","tui"],"latest_commit_sha":null,"homepage":"https://ayande.xyz","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ayan-de.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-06-10T06:16:21.000Z","updated_at":"2026-06-10T08:31:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ayan-de/heatmap","commit_stats":null,"previous_names":["ayan-de/heatmap"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ayan-de/heatmap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayan-de%2Fheatmap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayan-de%2Fheatmap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayan-de%2Fheatmap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayan-de%2Fheatmap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayan-de","download_url":"https://codeload.github.com/ayan-de/heatmap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayan-de%2Fheatmap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34827535,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"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":["calender","cli","commander","github","heatmap","terminal","tui"],"created_at":"2026-06-26T17:31:19.350Z","updated_at":"2026-06-26T17:31:19.952Z","avatar_url":"https://github.com/ayan-de.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# terminal-heatmap\n\nA premium, highly customizable, and interactive GitHub-like contribution heatmap generator for your terminal.\n\nVisualize activity, habits, tokens, or any daily metrics beautifully in standard shells with mouse hover coordinates, dynamic data keys, custom color themes, and emoji support.\n\n---\n\n## Features\n\n- 🎨 **Harmonious Predefined \u0026 Custom Themes**: Sleek predefined palettes (`github-green`, `github-dark`, `github-light`, `halloween`, `flame`, `ocean`, `cool`, `purple`, etc.) or construct your own dynamically!\n- 🕹️ **Interactive Hover TUI (`--interactive`)**: Turn the static text output into an alternate screen buffer console where moving your mouse over cell boxes displays live date and count info.\n- 📦 **Cell Style Presets**: Choose between `classic` (`■`), `double-block` (`██`), or plant-growth `emoji` presets (`⚪🌱🌿🌳🌴`).\n- 🎭 **Custom Emojis**: Supply your own 4-emoji or 5-emoji array to represent intensity levels.\n- 🔍 **Dynamic Key Auto-Detection**: Supports any daily data out of the box (e.g. tracks `\"TokenCount\"`, `\"commitCount\"`, or `\"count\"` automatically based on your JSON format).\n- 📱 **Responsive Rendering**: Dynamic column trimming that automatically fits the heatmap perfectly into your terminal width.\n\n---\n\n## Installation\n\nInstall globally via npm to use the CLI tool anywhere:\n```bash\nnpm install -g @thisisayande/terminal-heatmap\n```\n\nOr install locally in your project for programmatic API usage:\n```bash\nnpm install @thisisayande/terminal-heatmap\n```\n\n---\n\n## CLI Usage\n\nThe CLI requires daily contribution counts stored in a JSON file.\n\n### Input JSON Format\nThe input JSON must be an array of objects containing a `\"date\"` (YYYY-MM-DD) and a numerical count/value field (e.g. `\"count\"`, `\"TokenCount\"`, etc.):\n```json\n[\n  { \"date\": \"2026-06-01\", \"count\": 2 },\n  { \"date\": \"2026-06-02\", \"count\": 12 },\n  { \"date\": \"2026-06-03\", \"TokenCount\": 350 }\n]\n```\n\n### Basic Commands\n```bash\n# Render a basic static heatmap\nterminal-heatmap --json data.json\n\n# Read JSON directly from stdin\ncat data.json | terminal-heatmap --json -\n```\n\n### Interactive Hover Mode\nLaunch a premium console where mouse movement reveals coordinates, date, and counts:\n```bash\nterminal-heatmap --json data.json --interactive\n```\n*Press `q`, `Esc`, or `Ctrl+C` to cleanly exit and restore your terminal screen.*\n\n### Custom Themes \u0026 Cell Presets\n```bash\n# Apply a custom theme by passing 5 comma-separated hex colors (empty cell to highest intensity)\nterminal-heatmap --json data.json --theme \"#1e1b4b,#3b0764,#581c87,#7e22ce,#a855f7\"\n\n# Double solid block style\nterminal-heatmap --json data.json --preset double-block\n\n# Plant growth emoji style\nterminal-heatmap --json data.json --preset emoji\n\n# Custom 4-emoji list (level 0 defaults to ⚪)\nterminal-heatmap --json data.json --emojis \"🔴,🟡,🔵,🟢\"\n\n# Custom 5-emoji list (level 0 custom emoji)\nterminal-heatmap --json data.json --emojis \"❌,🔴,🟡,🔵,🟢\"\n```\n\n### Options List\n\n| Option | Shorthand | Description | Default |\n| :--- | :---: | :--- | :--- |\n| `--json \u003cfile\u003e` | | **Required**. Load JSON data (or `-` for stdin) | |\n| `--interactive` | `-i` | Enable mouse-hover TUI mode | `false` |\n| `--preset \u003cstyle\u003e`| | Select cell preset: `classic`, `double-block`, `emoji` | `classic` |\n| `--emojis \u003clist\u003e` | | Comma-separated list of 4 or 5 emojis | |\n| `--theme \u003cname\\|colors\u003e`| | Predefined theme name or 5 comma-separated hex colors | `github-green` |\n| `--char \u003cchar\u003e` | | Explicitly override the cell character symbol | `■` |\n| `--title \u003ctext\u003e` | | Add a title above the heatmap | `Contribution Heatmap`|\n| `--start \u003cdate\u003e` | | Start date (YYYY-MM-DD) | `1 year ago` |\n| `--end \u003cdate\u003e` | | End date (YYYY-MM-DD) | `today` |\n| `--monday` | | Start weeks on Monday instead of Sunday | `false` |\n| `--all-days` | | Print labels for all days of the week | `Mon/Wed/Fri` |\n| `--no-legend` | | Hide the intensity color legend | `false` |\n| `--no-month` | | Hide month headers | `false` |\n| `--no-day` | | Hide weekday labels | `false` |\n\n---\n\n## Programmatic API Usage\n\nYou can import and integrate the heatmap engine directly in Node.js/TypeScript code.\n\n### 1. Render a Static Heatmap String\n```javascript\nimport { renderHeatmap } from '@thisisayande/terminal-heatmap';\n\nconst data = [\n  { date: '2026-06-01', count: 3 },\n  { date: '2026-06-02', count: 15 }\n];\n\n// Passing custom theme colors directly as an object\nconst heatmapString = renderHeatmap(data, {\n  theme: {\n    colors: ['#111827', '#312e81', '#3730a3', '#4338ca', '#4f46e5']\n  },\n  title: 'My Project Metrics',\n  preset: 'double-block',\n  startDate: '2026-05-01',\n  endDate: '2026-06-15'\n});\n\nconsole.log(heatmapString);\n```\n\n### 2. Run the Interactive Hover Mode\n```javascript\nimport { startInteractiveHeatmap } from '@thisisayande/terminal-heatmap';\n\nconst data = [\n  { date: '2026-06-01', TokenCount: 50 },\n  { date: '2026-06-02', TokenCount: 200 }\n];\n\n// This enters the TUI alternate buffer and listens to mouse hover movements\nstartInteractiveHeatmap(data, {\n  theme: 'cool',\n  title: 'Habit Tracker',\n  emojis: ['🔴', '🟡', '🔵', '🟢'] // Custom 4-emoji intensity\n});\n```\n\n---\n\n## Development\n\nIf you'd like to work on this package locally:\n\n1. Clone the repository and install dependencies:\n   ```bash\n   npm install\n   ```\n2. Build code:\n   ```bash\n   npm run build\n   ```\n3. Run the test suite:\n   ```bash\n   npm run test\n   ```\n\n---\n\n## License\n\nMIT © [ayande](https://github.com/thisisayande)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayan-de%2Fheatmap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayan-de%2Fheatmap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayan-de%2Fheatmap/lists"}