cci.

active

Claude Code Inspector: usage, tokens, costs, tools, sessions and billing blocks, visualized.

$ cat github.com/arnonsang/cci/README.mdsynced 2026-11-19 10:33 ICT · rebuilt daily

Visualize and analyze Claude Code usage patterns: tokens, costs, tools, sessions, and billing blocks.

Dual data pipeline: real-time hook capture + historical JSONL import into SQLite, surfaced via CLI reports, dashboards (TUI + Web).

Installation

Installation Globally via npm

Install directly from GitHub and register the cci command system-wide:

npm install -g arnonsang/cci

Local Development

Clone and build the project manually for local development or custom modification:

# Clone the repository
git clone https://github.com/arnonsang/cci.git
cd cci

# Install dependencies and build
npm install
npm run build

# Link globally (optional)
npm link

Quick Start

  1. Initialize: Install hooks into ~/.claude/settings.json and create the local database.
    cci init
  2. Import History: Import existing transcripts and usage data from ~/.claude.
    cci backfill
  3. Explore:
    • cci daily - View today’s usage in the terminal.
    • cci dashboard - Launch the interactive TUI.
    • cci dashboard --web - Open the browser-based dashboard.

Tip: The dashboard server now auto-starts in the background whenever you start a Claude session!

CLI Command Reference

Setup & Maintenance

Command Options Description
init --no-hooks, --http Install hooks and setup DB. --http enables live web hooks.
uninstall - Remove hooks from settings.json and delete all local data.
backfill --project <name> Deep scan ~/.claude for historical session data.
parse - Incremental parse of events.jsonl into SQLite.

Reports

Command Key Options Description
daily -b, -p <proj>, -s <since>, -z <tz> Daily token usage and costs.
weekly -b, -p <proj> Weekly aggregated report.
monthly -b, -p <proj> Monthly aggregated report.
session --json, --project <name> Per-session usage details and duration.
blocks --active, --recent Track 5-hour billing windows and burn rates.
tools --by-project, --by-day Analytics on how many times each tool is called.
statusline --json, --session-length <h> Compact summary for shell prompts.

Dashboard

Command Key Options Description
dashboard - Launch the Ink TUI (Interactive Terminal UI).
dashboard --web, --port <p>, --no-open Start the Web Dashboard server.

System & Config

Command Description
config list Show all active configuration settings.
config set <k> <v> Modify settings (e.g., dashboardPort, costMode).
pricing Show current model pricing (--fetch to update from LiteLLM).
mcp Start the Model Context Protocol server.

Dashboard Surfaces

Web Dashboard

A rich, browser-based interface with real-time SSE event feeds, interactive charts (Recharts), and session filtering.

  • Default Port: 11596
  • Theme: Claude Editorial (Warm beige, serif typography).
  • Disclaimer: Labeled as a community-driven, third-party tool.

TUI

A React-based interactive terminal interface powered by ink.

  • Navigation: Keys 1-4 to switch tabs, arrows to scroll, q to quit.
  • Aesthetic: Unified Claude branding with 256-color hex support.

Auto-Start Daemon

CCI includes an intelligent auto-start mechanism. When you run cci init, it installs a SessionStart hook in Claude. This hook silently attempts to wake up the cci dashboard server in the background if it’s not already running, ensuring your data is always being collected and ready for the web UI.

Architecture

graph TD
    CC[Claude Code] -- "Async Hooks (Bash/HTTP)" --> Hooks{Hooks}
    
    Hooks -- "Append JSONL" --> JSONL[events.jsonl]
    Hooks -- "POST Event" --> Hono[Hono Web Server]
    
    JSONL -- "Incremental Parse" --> DB[(SQLite cci.db)]
    
    DB --> CLI[CLI Reports]
    DB --> TUI[Ink Interactive TUI]
    DB --> Hono
    DB --> MCP[MCP Server]
    
    Hono -- "SSE Real-time Feed" --> Web[Web Dashboard]

Uninstallation

To remove all hooks, scripts, and the SQLite database:

cci uninstall

If you installed globally via npm, also run:

npm uninstall -g arnonsang/cci

License

MIT

This application is not affiliated with, endorsed by, or an official product of Anthropic.

continue reading on github →