https://github.com/ayan-de/heatmap
Generate beautiful, customizable contribution heatmaps in your terminal with custom color themes, emoji cells, interactive hover mode, and auto-detecting data keys.
https://github.com/ayan-de/heatmap
calender cli commander github heatmap terminal tui
Last synced: about 21 hours ago
JSON representation
Generate beautiful, customizable contribution heatmaps in your terminal with custom color themes, emoji cells, interactive hover mode, and auto-detecting data keys.
- Host: GitHub
- URL: https://github.com/ayan-de/heatmap
- Owner: ayan-de
- Created: 2026-06-10T06:16:21.000Z (17 days ago)
- Default Branch: main
- Last Pushed: 2026-06-10T08:30:45.000Z (17 days ago)
- Last Synced: 2026-06-10T10:15:43.594Z (17 days ago)
- Topics: calender, cli, commander, github, heatmap, terminal, tui
- Language: TypeScript
- Homepage: https://ayande.xyz
- Size: 17.7 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# terminal-heatmap
A premium, highly customizable, and interactive GitHub-like contribution heatmap generator for your terminal.
Visualize activity, habits, tokens, or any daily metrics beautifully in standard shells with mouse hover coordinates, dynamic data keys, custom color themes, and emoji support.
---
## Features
- 🎨 **Harmonious Predefined & Custom Themes**: Sleek predefined palettes (`github-green`, `github-dark`, `github-light`, `halloween`, `flame`, `ocean`, `cool`, `purple`, etc.) or construct your own dynamically!
- 🕹️ **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.
- 📦 **Cell Style Presets**: Choose between `classic` (`■`), `double-block` (`██`), or plant-growth `emoji` presets (`⚪🌱🌿🌳🌴`).
- 🎭 **Custom Emojis**: Supply your own 4-emoji or 5-emoji array to represent intensity levels.
- 🔍 **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).
- 📱 **Responsive Rendering**: Dynamic column trimming that automatically fits the heatmap perfectly into your terminal width.
---
## Installation
Install globally via npm to use the CLI tool anywhere:
```bash
npm install -g @thisisayande/terminal-heatmap
```
Or install locally in your project for programmatic API usage:
```bash
npm install @thisisayande/terminal-heatmap
```
---
## CLI Usage
The CLI requires daily contribution counts stored in a JSON file.
### Input JSON Format
The 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.):
```json
[
{ "date": "2026-06-01", "count": 2 },
{ "date": "2026-06-02", "count": 12 },
{ "date": "2026-06-03", "TokenCount": 350 }
]
```
### Basic Commands
```bash
# Render a basic static heatmap
terminal-heatmap --json data.json
# Read JSON directly from stdin
cat data.json | terminal-heatmap --json -
```
### Interactive Hover Mode
Launch a premium console where mouse movement reveals coordinates, date, and counts:
```bash
terminal-heatmap --json data.json --interactive
```
*Press `q`, `Esc`, or `Ctrl+C` to cleanly exit and restore your terminal screen.*
### Custom Themes & Cell Presets
```bash
# Apply a custom theme by passing 5 comma-separated hex colors (empty cell to highest intensity)
terminal-heatmap --json data.json --theme "#1e1b4b,#3b0764,#581c87,#7e22ce,#a855f7"
# Double solid block style
terminal-heatmap --json data.json --preset double-block
# Plant growth emoji style
terminal-heatmap --json data.json --preset emoji
# Custom 4-emoji list (level 0 defaults to ⚪)
terminal-heatmap --json data.json --emojis "🔴,🟡,🔵,🟢"
# Custom 5-emoji list (level 0 custom emoji)
terminal-heatmap --json data.json --emojis "❌,🔴,🟡,🔵,🟢"
```
### Options List
| Option | Shorthand | Description | Default |
| :--- | :---: | :--- | :--- |
| `--json ` | | **Required**. Load JSON data (or `-` for stdin) | |
| `--interactive` | `-i` | Enable mouse-hover TUI mode | `false` |
| `--preset `| | Select cell preset: `classic`, `double-block`, `emoji` | `classic` |
| `--emojis <list>` | | Comma-separated list of 4 or 5 emojis | |
| `--theme <name\|colors>`| | Predefined theme name or 5 comma-separated hex colors | `github-green` |
| `--char <char>` | | Explicitly override the cell character symbol | `■` |
| `--title <text>` | | Add a title above the heatmap | `Contribution Heatmap`|
| `--start <date>` | | Start date (YYYY-MM-DD) | `1 year ago` |
| `--end <date>` | | End date (YYYY-MM-DD) | `today` |
| `--monday` | | Start weeks on Monday instead of Sunday | `false` |
| `--all-days` | | Print labels for all days of the week | `Mon/Wed/Fri` |
| `--no-legend` | | Hide the intensity color legend | `false` |
| `--no-month` | | Hide month headers | `false` |
| `--no-day` | | Hide weekday labels | `false` |
---
## Programmatic API Usage
You can import and integrate the heatmap engine directly in Node.js/TypeScript code.
### 1. Render a Static Heatmap String
```javascript
import { renderHeatmap } from '@thisisayande/terminal-heatmap';
const data = [
{ date: '2026-06-01', count: 3 },
{ date: '2026-06-02', count: 15 }
];
// Passing custom theme colors directly as an object
const heatmapString = renderHeatmap(data, {
theme: {
colors: ['#111827', '#312e81', '#3730a3', '#4338ca', '#4f46e5']
},
title: 'My Project Metrics',
preset: 'double-block',
startDate: '2026-05-01',
endDate: '2026-06-15'
});
console.log(heatmapString);
```
### 2. Run the Interactive Hover Mode
```javascript
import { startInteractiveHeatmap } from '@thisisayande/terminal-heatmap';
const data = [
{ date: '2026-06-01', TokenCount: 50 },
{ date: '2026-06-02', TokenCount: 200 }
];
// This enters the TUI alternate buffer and listens to mouse hover movements
startInteractiveHeatmap(data, {
theme: 'cool',
title: 'Habit Tracker',
emojis: ['🔴', '🟡', '🔵', '🟢'] // Custom 4-emoji intensity
});
```
---
## Development
If you'd like to work on this package locally:
1. Clone the repository and install dependencies:
```bash
npm install
```
2. Build code:
```bash
npm run build
```
3. Run the test suite:
```bash
npm run test
```
---
## License
MIT © [ayande](https://github.com/thisisayande)