claude-matrix 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f223740ea18dd305956e0d1a21b8424dec3a19bd467e9a78310fb40702f7697d
+  data.tar.gz: 5136193a040c79ba2b55d7de2720a89db388acfa78b5f825c19783ab7878e0b8
+SHA512:
+  metadata.gz: 50c596495620a83d34d38c604ddd1f6f3d951f4c624c788ad056a0f47a9b10e63e352c178d94a00a918b8c041c4ac8817cb4ac41e00f7b8258181894910e1449
+  data.tar.gz: f016892c5c0e9d120fa2bba9be0004d3e823dc39729db5e3060e7eba9fc579f413ddea8e19bdd722be3166897f7be51e7687e569d37d24ee7dba9796fb07bc24

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [1.0.0] - 2026-03-10
+
+### Added
+- Full-screen btop-style TUI dashboard
+- Streaks: current, longest, active days
+- Personal bests: longest session, most productive day, busiest hour, favorite tool
+- Work mode breakdown: Explore / Build / Test
+- Top tools ranked bar chart with gradient coloring
+- Tokens & cost panel with per-model cost estimation
+- Activity chart (last 30 days)
+- Hourly heatmap (day × hour, shown on taller terminals)
+- Time filters: Today / Week / Month / All Time (`t`/`w`/`m`/`a`)
+- Per-project breakdown with git branch tracking
+- `stats` command with `--today`, `--week`, `--month` flags
+- `doctor` command to verify data sources
+- Zero configuration — reads `~/.claude/` directly

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kapil Bhosale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,183 @@
+# Claude Matrix
+
+A privacy-first, terminal analytics dashboard for [Claude Code](https://claude.ai/code). It reads your local Claude Code session data (reads ~/.claude/ directly, never touches the network) — sessions, tools, tokens, cost, streaks — and renders a live TUI right in your terminal. No cloud, no API calls, no configuration. Just run it and see your usage, coding patterns.
+
+
+![Claude Matrix Dashboard](./docs/screenshot-1.png)
+
+---
+
+## Features
+
+- **Full-screen TUI** — btop-inspired two-column layout that fills your terminal exactly, no scrolling
+- **Streaks** — current and longest coding streaks, active days
+- **Personal bests** — longest session, most productive day, busiest hour, favorite tool
+- **Work mode** — Explore / Build / Test breakdown based on tool usage patterns
+- **Top tools** — ranked bar chart with gradient coloring
+- **Tokens & cost** — input/output token bars with estimated cost (color-coded green → yellow → red)
+- **Activity chart** — last 30-day bar chart
+- **Heatmap** — sessions by day-of-week × hour (on taller terminals)
+- **Time filters** — Today / Week / Month / All Time, switch with a single key
+- **100% local** — reads `~/.claude/` directly, never touches the network
+- **Git branch tracking** — shows the branch you were on per project
+
+---
+
+## Requirements
+
+- Ruby 3.0+
+- macOS or Linux
+- Claude Code installed and used at least once
+- A terminal with Unicode and color support (iTerm2, Warp, Kitty, Alacritty, etc.)
+
+---
+
+## Installation
+
+```bash
+gem install claude-matrix
+```
+
+**From source:**
+
+```bash
+git clone https://github.com/kapilbhosale/claude-matrix
+cd claude-matrix
+bundle install
+bundle exec bin/claude-matrix
+```
+
+---
+
+## Usage
+
+### Launch the dashboard
+
+```bash
+claude-matrix
+# or
+claude-matrix dashboard
+```
+
+### Dashboard keyboard controls
+
+| Key | Action |
+|-----|--------|
+| `t` | Filter: Today |
+| `w` | Filter: This Week |
+| `m` | Filter: This Month |
+| `a` | Filter: All Time |
+| `r` | Refresh data |
+| `q` | Quit |
+
+### Quick stats (no TUI)
+
+### Check data sources
+
+```bash
+claude-matrix doctor
+```
+
+---
+
+## How it works
+
+Claude Code writes session transcripts to `~/.claude/projects/`. Claude Matrix reads those JSONL files directly on each refresh — no background daemon, no database, no setup.
+
+```
+~/.claude/
+├── stats-cache.json          # pre-computed stats (optional bonus)
+├── history.jsonl             # all prompts ever typed
+└── projects/
+    └── {encoded-path}/
+        └── {session-uuid}.jsonl   ← parsed on every run
+```
+
+Each session file is parsed for:
+- Tool calls (`Bash`, `Read`, `Write`, `Edit`, …)
+- Token usage and model name (for cost estimation)
+- Timestamps (for streaks and heatmap)
+- Git branch (shown in Projects panel)
+
+---
+
+## Cost estimation
+
+Estimated costs use published Claude API pricing (per 1M tokens):
+
+| Model | Input | Output | Cache read | Cache write |
+|-------|------:|-------:|-----------:|------------:|
+| claude-opus-4.x | $15 | $75 | $1.50 | $18.75 |
+| claude-sonnet-4.x | $3 | $15 | $0.30 | $3.75 |
+| claude-haiku-4.x | $0.80 | $4 | $0.08 | $1.00 |
+
+> These are estimates. Actual billed amounts may differ.
+
+---
+
+## Project structure
+
+```
+claude-matrix/
+├── bin/
+│   └── claude-matrix              # executable
+├── lib/
+│   ├── claude_matrix.rb           # entry point
+│   └── claude_matrix/
+│       ├── cli.rb                 # command router + interactive loop
+│       ├── readers/
+│       │   ├── session_parser.rb  # JSONL parser
+│       │   ├── stats_reader.rb    # stats-cache.json reader
+│       │   └── history_reader.rb  # history.jsonl reader
+│       ├── analyzers/
+│       │   └── metrics.rb         # streaks, work modes, cost, heatmap grid
+│       └── visualizers/
+│           └── dashboard.rb       # full-screen TUI renderer
+├── Gemfile
+├── claude-matrix.gemspec
+└── README.md
+```
+
+---
+
+
+
+## Releasing a new version
+
+1. Bump `VERSION` in `lib/claude_matrix/version.rb`
+2. Add an entry to `CHANGELOG.md`
+3. Commit, tag, and push:
+
+```bash
+git add -A
+git commit -m "Release v1.x.x"
+git tag v1.x.x
+git push && git push --tags
+```
+
+GitHub Actions picks up the tag and publishes to RubyGems automatically.
+
+> **One-time setup:** add your RubyGems API key as a repository secret named `RUBYGEMS_API_KEY`
+> (GitHub repo → Settings → Secrets and variables → Actions → New repository secret).
+> Get your key from [rubygems.org/profile/edit](https://rubygems.org/profile/edit).
+
+---
+
+## Contributing
+
+1. Fork the repo
+2. Create a branch: `git checkout -b my-feature`
+3. Make your changes
+4. Open a pull request
+
+Bug reports and feature requests are welcome via [GitHub Issues](https://github.com/kapilbhosale/claude-matrix/issues).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+*Built with Ruby, [TTY toolkit](https://ttytoolkit.org), and [Pastel](https://github.com/piotrmurach/pastel).*

data/bin/claude-matrix

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "claude_matrix/cli"
+
+ClaudeMatrix::CLI.run(ARGV)

data/lib/claude_matrix/analyzers/metrics.rb

@@ -0,0 +1,206 @@
+require "date"
+
+module ClaudeMatrix
+  module Analyzers
+    class Metrics
+      # Claude pricing per 1M tokens (as of early 2026)
+      MODEL_PRICING = {
+        "claude-opus-4-6"             => { input: 15.0,  output: 75.0,  cache_read: 1.5,  cache_write: 18.75 },
+        "claude-opus-4-5"             => { input: 15.0,  output: 75.0,  cache_read: 1.5,  cache_write: 18.75 },
+        "claude-sonnet-4-6"           => { input: 3.0,   output: 15.0,  cache_read: 0.3,  cache_write: 3.75  },
+        "claude-sonnet-4-5"           => { input: 3.0,   output: 15.0,  cache_read: 0.3,  cache_write: 3.75  },
+        "claude-haiku-4-5-20251001"   => { input: 0.8,   output: 4.0,   cache_read: 0.08, cache_write: 1.0   },
+        "claude-haiku-4-5"            => { input: 0.8,   output: 4.0,   cache_read: 0.08, cache_write: 1.0   },
+      }.freeze
+
+      DEFAULT_PRICE = { input: 3.0, output: 15.0, cache_read: 0.3, cache_write: 3.75 }.freeze
+
+      WORK_MODE_TOOLS = {
+        exploration: %w[Read Glob Grep WebSearch WebFetch read_file list_files search_files grep],
+        building:    %w[Write Edit NotebookEdit write_to_file edit_file new_file],
+        testing:     %w[Bash execute_command bash]
+      }.freeze
+
+      def self.compute(sessions)
+        return empty_metrics if sessions.empty?
+
+        total_input    = sessions.sum { |s| s[:input_tokens] }
+        total_output   = sessions.sum { |s| s[:output_tokens] }
+        total_cache_r  = sessions.sum { |s| s[:cache_read] }
+        total_cache_w  = sessions.sum { |s| s[:cache_create] }
+
+        all_tools   = sessions.flat_map { |s| s[:tools] }
+        tool_counts = all_tools.tally.sort_by { |_, c| -c }.to_h
+
+        daily = build_daily_activity(sessions)
+        streaks = calculate_streaks(daily)
+        hour_counts = build_hour_counts(sessions)
+
+        longest = sessions.max_by { |s| s[:duration_secs] }
+        most_messages = sessions.max_by { |s| s[:message_count] }
+
+        projects = sessions.group_by { |s| s[:project] }
+        most_active_project = projects.max_by { |_, ss| ss.sum { |s| s[:message_count] } }&.first
+
+        {
+          total_sessions:    sessions.size,
+          total_messages:    sessions.sum { |s| s[:message_count] },
+          total_tool_calls:  all_tools.size,
+          total_input_tokens:  total_input,
+          total_output_tokens: total_output,
+          total_cache_read:    total_cache_r,
+          total_cache_write:   total_cache_w,
+          estimated_cost:    estimate_cost(sessions),
+          first_session:     sessions.map { |s| s[:started_at] }.min,
+          projects:          projects.keys.size,
+          project_names:     projects.keys,
+          most_active_project: most_active_project,
+          tool_counts:       tool_counts,
+          top_tools:         tool_counts.first(10).to_h,
+          favorite_tool:     tool_counts.first&.first,
+          daily_activity:    daily,
+          streaks:           streaks,
+          hour_counts:       hour_counts,
+          hour_day_grid:     build_hour_day_grid(sessions),
+          work_modes:        calculate_work_modes(all_tools),
+          longest_session:   longest,
+          most_messages_session: most_messages,
+          most_productive_day: most_productive_day(daily),
+          busiest_hour:      hour_counts.max_by { |_, c| c }&.first,
+          models_used:       sessions.map { |s| s[:model] }.compact.uniq,
+          per_project:       build_per_project(sessions)
+        }
+      end
+
+      def self.estimate_cost(sessions)
+        total = 0.0
+        sessions.each do |s|
+          price = find_price(s[:model])
+          total += (s[:input_tokens].to_f  / 1_000_000) * price[:input]
+          total += (s[:output_tokens].to_f / 1_000_000) * price[:output]
+          total += (s[:cache_read].to_f    / 1_000_000) * price[:cache_read]
+          total += (s[:cache_create].to_f  / 1_000_000) * price[:cache_write]
+        end
+        total.round(4)
+      end
+
+      private
+
+      def self.find_price(model)
+        return DEFAULT_PRICE unless model
+        MODEL_PRICING.find { |k, _| model.start_with?(k) }&.last || DEFAULT_PRICE
+      end
+
+      def self.build_daily_activity(sessions)
+        daily = Hash.new { |h, k| h[k] = { sessions: 0, messages: 0, tools: 0 } }
+
+        sessions.each do |s|
+          date = s[:started_at].to_date.to_s
+          daily[date][:sessions]  += 1
+          daily[date][:messages]  += s[:message_count]
+          daily[date][:tools]     += s[:tool_count]
+        end
+
+        daily.sort.to_h
+      end
+
+      def self.calculate_streaks(daily)
+        return { current: 0, longest: 0, active_days: 0 } if daily.empty?
+
+        dates = daily.keys.map { |d| Date.parse(d) }.sort
+        active_days = dates.size
+
+        # Current streak
+        current = 0
+        expected = Date.today
+        dates.sort.reverse.each do |date|
+          break if date < expected - 1
+          if date == expected || date == expected - 1
+            current += 1
+            expected = date - 1
+          end
+        end
+
+        # Also allow today to count if used today
+        current = 1 if current == 0 && dates.include?(Date.today)
+
+        # Longest streak
+        longest = 1
+        temp = 1
+        dates.each_cons(2) do |d1, d2|
+          if (d2 - d1).to_i == 1
+            temp += 1
+            longest = [longest, temp].max
+          else
+            temp = 1
+          end
+        end
+
+        { current: current, longest: longest, active_days: active_days }
+      end
+
+      def self.build_hour_counts(sessions)
+        counts = Hash.new(0)
+        sessions.each do |s|
+          counts[s[:started_at].hour] += 1
+        end
+        counts
+      end
+
+      def self.calculate_work_modes(tools)
+        total = tools.size.to_f
+        return { exploration: 0, building: 0, testing: 0 } if total.zero?
+
+        result = {}
+        WORK_MODE_TOOLS.each do |mode, mode_tools|
+          count = tools.count { |t| mode_tools.include?(t) }
+          result[mode] = (count / total * 100).round
+        end
+        result
+      end
+
+      def self.most_productive_day(daily)
+        return nil if daily.empty?
+        date, data = daily.max_by { |_, d| d[:sessions] }
+        { date: date, sessions: data[:sessions], messages: data[:messages] }
+      end
+
+      def self.build_hour_day_grid(sessions)
+        # 7 rows (wday: 0=Sun..6=Sat) × 24 cols (hours)
+        grid = Array.new(7) { Array.new(24, 0) }
+        sessions.each do |s|
+          grid[s[:started_at].wday][s[:started_at].hour] += 1
+        end
+        grid
+      end
+
+      def self.build_per_project(sessions)
+        sessions.group_by { |s| s[:project] }.transform_values do |ss|
+          {
+            sessions:     ss.size,
+            messages:     ss.sum { |s| s[:message_count] },
+            tools:        ss.sum { |s| s[:tool_count] },
+            last_active:  ss.map { |s| s[:ended_at] }.max,
+            branches:     ss.map { |s| s[:git_branch] }.compact.uniq
+          }
+        end.sort_by { |_, v| -v[:sessions] }.to_h
+      end
+
+      def self.empty_metrics
+        {
+          total_sessions: 0, total_messages: 0, total_tool_calls: 0,
+          total_input_tokens: 0, total_output_tokens: 0,
+          total_cache_read: 0, total_cache_write: 0, hour_day_grid: Array.new(7) { Array.new(24, 0) },
+          estimated_cost: 0.0, first_session: nil, projects: 0,
+          project_names: [], most_active_project: nil,
+          tool_counts: {}, top_tools: {}, favorite_tool: nil,
+          daily_activity: {}, streaks: { current: 0, longest: 0, active_days: 0 },
+          hour_counts: {}, work_modes: { exploration: 0, building: 0, testing: 0 },
+          longest_session: nil, most_messages_session: nil,
+          most_productive_day: nil, busiest_hour: nil,
+          models_used: [], per_project: {}
+        }
+      end
+    end
+  end
+end

data/lib/claude_matrix/cli.rb

@@ -0,0 +1,177 @@
+require_relative "../claude_matrix"
+require "tty-reader"
+require "tty-cursor"
+require "date"
+
+module ClaudeMatrix
+  class CLI
+    def self.run(args)
+      case (args.first || "dashboard")
+      when "dashboard", "d", nil then DashboardCommand.new.run
+      when "stats"                then StatsCommand.new(args[1..]).run
+      when "sync"                 then SyncCommand.new.run
+      when "doctor"               then DoctorCommand.new.run
+      when "version", "--version", "-v" then puts "claude-matrix #{VERSION}"
+      when "help", "--help", "-h"       then puts help_text
+      else
+        warn "Unknown command: #{args.first}"
+        warn help_text
+        exit 1
+      end
+    end
+
+    def self.help_text
+      <<~HELP
+        Claude Matrix #{VERSION} — Claude Code Analytics Dashboard
+
+        Usage:
+          claude-matrix              Launch interactive dashboard
+          claude-matrix stats        Print stats to stdout
+          claude-matrix stats --today / --week / --month
+          claude-matrix doctor       Check data sources
+          claude-matrix version
+
+        Dashboard keys:
+          t/w/m/a  Filter: Today / Week / Month / All Time
+          r        Refresh
+          q        Quit
+      HELP
+    end
+
+    # ─── Interactive dashboard ────────────────────────────────────────────────
+
+    class DashboardCommand
+      FILTERS = %i[today week month all].freeze
+
+      def run
+        cursor  = TTY::Cursor
+        reader  = TTY::Reader.new(interrupt: :exit)
+        filter  = :all
+        all_sessions = nil  # lazy-load once, refresh on 'r'
+
+        loop do
+          all_sessions ||= ClaudeMatrix.load_sessions
+          metrics = Analyzers::Metrics.compute(filter_sessions(all_sessions, filter))
+
+          print cursor.clear_screen
+          print cursor.move_to(0, 0)
+          Visualizers::Dashboard.new(metrics, filter: filter).render
+
+          char = reader.read_char
+          case char&.downcase
+          when "q", "\e" then break
+          when "r"        then all_sessions = nil  # force reload
+          when "t"        then filter = :today
+          when "w"        then filter = :week
+          when "m"        then filter = :month
+          when "a"        then filter = :all
+          end
+        end
+      rescue TTY::Reader::InputInterrupt
+        # clean exit on Ctrl-C
+      ensure
+        puts TTY::Cursor.show
+        puts  # move off last dashboard line
+      end
+
+      private
+
+      def filter_sessions(sessions, filter)
+        case filter
+        when :today
+          d = Date.today
+          sessions.select { |s| s[:started_at].to_date == d }
+        when :week
+          start = Date.today - Date.today.wday
+          sessions.select { |s| s[:started_at].to_date >= start }
+        when :month
+          sessions.select { |s|
+            s[:started_at].year == Date.today.year &&
+            s[:started_at].month == Date.today.month
+          }
+        else
+          sessions
+        end
+      end
+    end
+
+    # ─── Stats command ────────────────────────────────────────────────────────
+
+    class StatsCommand
+      def initialize(flags)
+        @filter = if flags.include?("--today") then :today
+                  elsif flags.include?("--week")  then :week
+                  elsif flags.include?("--month") then :month
+                  else :all
+                  end
+      end
+
+      def run
+        all  = ClaudeMatrix.load_sessions
+        sess = filter_sessions(all, @filter)
+        m    = Analyzers::Metrics.compute(sess)
+
+        label = { today: "Today", week: "This Week", month: "This Month", all: "All Time" }[@filter]
+        puts "\n  Claude Matrix — #{label}"
+        puts "  " + "─" * 40
+        puts "  Sessions:    #{m[:total_sessions]}"
+        puts "  Messages:    #{m[:total_messages]}"
+        puts "  Tools:       #{m[:total_tool_calls]}"
+        puts "  Tokens In:   #{fmt(m[:total_input_tokens])}"
+        puts "  Tokens Out:  #{fmt(m[:total_output_tokens])}"
+        puts "  Est. Cost:   $#{"%.4f" % m[:estimated_cost]}"
+        puts "  Streak:      #{m[:streaks][:current]} days (best: #{m[:streaks][:longest]})"
+        puts "  Top Tool:    #{m[:favorite_tool]} (#{m[:tool_counts][m[:favorite_tool]]})" if m[:favorite_tool]
+        puts
+      end
+
+      private
+
+      def filter_sessions(sessions, filter)
+        DashboardCommand.new.send(:filter_sessions, sessions, filter)
+      end
+
+      def fmt(n)
+        n >= 1_000_000 ? "%.1fM" % (n / 1_000_000.0) :
+        n >= 1_000     ? "%.1fK" % (n / 1_000.0) : n.to_s
+      end
+    end
+
+    # ─── Sync command ─────────────────────────────────────────────────────────
+
+    class SyncCommand
+      def run
+        files = Readers::SessionParser.jsonl_files
+        puts "\nScanning #{files.size} session files..."
+        count = 0
+        files.each_with_index do |f, i|
+          print "\rParsing #{i + 1}/#{files.size}..."
+          count += 1 if Readers::SessionParser.parse_file(f)
+        end
+        puts "\rDone! #{count}/#{files.size} sessions parsed.   "
+        puts "Run 'claude-matrix' to view the dashboard."
+      end
+    end
+
+    # ─── Doctor command ───────────────────────────────────────────────────────
+
+    class DoctorCommand
+      def run
+        puts "\n  Claude Matrix — Doctor\n  " + "─" * 36
+        check "~/.claude/ exists",            Dir.exist?(File.expand_path("~/.claude"))
+        check "~/.claude/projects/ exists",   Dir.exist?(File.expand_path("~/.claude/projects"))
+        check "~/.claude/history.jsonl",      File.exist?(File.expand_path("~/.claude/history.jsonl"))
+        check "stats-cache.json",             Readers::StatsReader.available?
+        files = Readers::SessionParser.jsonl_files
+        check "Session files found (#{files.size})", files.any?
+        puts
+      end
+
+      private
+
+      def check(label, ok)
+        puts "  #{ok ? "\e[32m✓\e[0m" : "\e[31m✗\e[0m"}  #{label}"
+      end
+    end
+  end
+end

data/lib/claude_matrix/readers/history_reader.rb

@@ -0,0 +1,38 @@
+require "json"
+
+module ClaudeMatrix
+  module Readers
+    class HistoryReader
+      HISTORY_PATH = File.expand_path("~/.claude/history.jsonl")
+
+      def self.read
+        return [] unless File.exist?(HISTORY_PATH)
+
+        File.readlines(HISTORY_PATH, chomp: true).filter_map do |line|
+          JSON.parse(line)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      def self.top_words(limit: 10)
+        stop_words = %w[i a the an is it in on at to for of and or but
+                        this that with from can you what how do be have
+                        are was were will would could should may might
+                        its your my we our let me now please just also
+                        if so there not no yes then when they he she]
+
+        all_words = read.flat_map do |entry|
+          text = entry["display"].to_s.downcase
+          text.scan(/[a-z]{3,}/)
+        end
+
+        all_words
+          .reject { |w| stop_words.include?(w) }
+          .tally
+          .sort_by { |_, count| -count }
+          .first(limit)
+      end
+    end
+  end
+end