ccusage-dashboard

A terminal UI dashboard that aggregates Claude Code usage and cost data from multiple machines (local + remote via SSH) into a single interactive interface.

Built with TypeScript, React (Ink), and SQLite.

Features

• Multi-instance monitoring - Track usage across local and remote machines simultaneously
• Auto-discovery - Automatically finds remote hosts from ~/.ssh/config
• Four data views - Daily breakdown, monthly trends (ASCII bar charts), session details, and 5-hour billing block analysis
• Summary panel - At-a-glance today/week/month cost totals with per-instance breakdown
• Cost alerts - Warning banners when spending approaches configurable thresholds
• Auto-refresh - Configurable refresh interval with countdown timer
• Filtering - Interactive date range and instance filtering
• Offline resilience - Falls back to cached SQLite data when remote hosts are unreachable
• Keyboard-driven - Full keyboard navigation with help overlay

Prerequisites

• Node.js >= 18
• ccusage installed on each machine you want to monitor
• SSH access configured for remote machines (key-based auth recommended)

Installation

git clone <repo-url>
cd multi_instance
npm install
npm run build

Usage

# Run the dashboard
node dist/cli.js

# Monitor specific hosts
node dist/cli.js --hosts local,labpc,gpu-server

# Set refresh interval (seconds)
node dist/cli.js --interval 60

# Filter by date range
node dist/cli.js --since 20260101 --until 20260131

CLI Options

| Flag | Description | Default | |------|-------------|---------| | --hosts <list> | Comma-separated hosts to monitor | All SSH hosts + local | | --since <YYYYMMDD> | Start date for data range | - | | --until <YYYYMMDD> | End date for data range | - | | --interval <seconds> | Auto-refresh interval | 300 |

Keyboard Shortcuts

| Key | Action | |-----|--------| | 1 - 4 | Switch tabs (Daily / Monthly / Sessions / Blocks) | | j / Down | Next row | | k / Up | Previous row | | Enter | Expand/collapse row details | | r | Manual refresh | | f | Open filter dialog | | ? | Toggle help overlay | | q / Ctrl+C | Quit |

Configuration

Create ~/.ccusage-dashboard.json (or ~/.config/ccusage-dashboard/config.json):

{
  "refreshInterval": 300,
  "timezone": "America/New_York",
  "dataDir": "~/.ccusage-dashboard",
  "thresholds": {
    "global": {
      "dailyLimit": 10,
      "monthlyLimit": 100
    },
    "perInstance": {
      "labpc": { "dailyLimit": 5 },
      "h100": { "monthlyLimit": 50 }
    }
  }
}

Development

# Watch mode (recompile on changes)
npm run dev

# Type checking
npm run typecheck

# Run tests
npm test

Project Structure

src/
  cli.tsx              # CLI entry point
  app.tsx              # Main App component
  types.ts             # Shared TypeScript interfaces
  config.ts            # Config file loader
  ssh-config-parser.ts # SSH host discovery
  resolve-config.ts    # Merge CLI flags + config + SSH hosts
  components/          # Ink React components (views, dialogs, overlays)
  hooks/               # React hooks (data fetching, refresh, navigation)
  fetchers/            # Multi-instance data fetching (local + SSH)
  db/                  # SQLite schema and repository
  utils/               # Color assignment, alert computation

License

ISC