stackpulse

Generate beautiful, shareable cards for your AI coding tool usage

Quick Start • Supported Tools • Themes • Config File • How It Works

What is stackpulse?

stackpulse scans your machine for AI coding tools, reads their local usage data (sessions, tokens, cost), and generates a shareable HTML card with:

• Per-tool usage breakdown with model details
• Donut chart with smart metric selection
• GitHub-style activity heatmap (per-tool rows)
• Save as PNG, PDF, or share on X — all from the card itself

One command. No API keys. No data leaves your machine.

npx stackpulse

Quick Start

# Run directly (no install needed)
npx stackpulse

# Or install globally
npm install -g stackpulse
stackpulse

The interactive wizard walks you through 3 steps:

1. Select tools — auto-detected from your machine + manual entry
2. Choose metrics — sessions, tokens, cost, commits, lines written
3. Customize — title, handle, theme, output filename

Output: stackpulse.html (open in browser, click "Save as PNG")

Supported Tools

stackpulse supports 13 AI coding tools across 4 data source types:

Full data (sessions + tokens + cost + heatmap)

Token data (sessions + tokens + heatmap)

Session data (sessions only)

Git-based

Tools not installed on your machine can still be added manually during the wizard.

Themes

7 built-in themes, selectable in the wizard or via --theme:

stackpulse --theme cosmic

Config File

Skip the wizard entirely with a YAML or JSON config:

# Generate a starter config
stackpulse --init ai-usage.yaml

# Run from config
stackpulse --config ai-usage.yaml

Example ai-usage.yaml:

title: My AI Coding Stack
timeframe: "2026 — All Time"
username: latentengineer_
theme: dark
metrics:
  - sessions
  - tokens_used
  - cost_usd
tools:
  claude_code:
    sessions: 312
    tokens_used: 23500
    cost_usd: 180
  codex:
    sessions: 88
    tokens_used: 605400
    cost_usd: 240
  cursor:
    sessions: 1971
  gemini:
    sessions: 200
    tokens_used: 8400

CLI Options

Usage: stackpulse [options]

Options:
  -V, --version          output version number
  -c, --config <file>    load from YAML or JSON config file
  -o, --output <name>    output base filename (default: "stackpulse")
  --no-png               skip PNG export prompt
  --theme <theme>        override theme (dark|light|cosmic|forge|arctic|verdant|neon)
  --title <title>        override card title
  --timeframe <range>    override timeframe text
  --username <handle>    override handle
  --init [file]          scaffold a starter YAML config
  -h, --help             display help

How It Works

stackpulse reads only local data — nothing is sent to any server.

┌─────────────────────────────────────────────────────┐
│                    Your Machine                      │
│                                                      │
│  ~/.claude/projects/    ──→  ccusage (sessions,      │
│  ~/.codex/              ──→  tokens, cost, models)   │
│  ~/.gemini/tmp/         ──→  JSONL parser (tokens)   │
│  ~/.kimi/sessions/      ──→  JSON parser (tokens)    │
│  ~/Library/.../Cursor/  ──→  SQLite reader (sessions)│
│  .aider.chat.history.md ──→  File parser (sessions)  │
│                                                      │
│         ↓ all local ↓                                │
│                                                      │
│  ┌─────────────────────────────────────────────┐     │
│  │              stackpulse.html                     │     │
│  │  ┌─────┬──────────────────────────────┐     │     │
│  │  │Donut│  Tool table with bars        │     │     │
│  │  │chart│  + model breakdown           │     │     │
│  │  └─────┴──────────────────────────────┘     │     │
│  │  ┌────────────────────────────────────┐     │     │
│  │  │  Per-tool activity heatmap         │     │     │
│  │  └────────────────────────────────────┘     │     │
│  │  [Save PNG] [Save PDF] [Share on X]         │     │
│  └─────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────┘

Export Options

The generated HTML card includes built-in export buttons:

• Save as PNG — captures the full card at 2x resolution via html2canvas
• Save as PDF — uses the browser's native print dialog
• Share on X — pre-filled tweet with your tool stats

Requirements

• Node.js 18+
• sqlite3 CLI (for Cursor/Antigravity/Roo Code/Kilo Code parsing)
• Tools you want to track must be installed and have local usage data

Privacy

stackpulse is fully offline. It:

• Reads only local files on your machine
• Never sends data to any server
• Never requires API keys or authentication
• The HTML output is a standalone file with no external dependencies (except Google Fonts)

Contributing

Contributions welcome! Especially:

• New tool parsers — if you use an AI coding tool not listed above
• Themes — add new visual themes to generator.js
• Bug reports — especially from tools with untested data formats

git clone https://github.com/KrishnaSathvik/stackpulse.git
cd stackpulse
npm install
node index.js

License

MIT © Krishna Sathvik Mantripragada

Built by @latentengineer_ · GitHub · npm