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
- Initialize: Install hooks into
~/.claude/settings.jsonand create the local database.cci init - Import History: Import existing transcripts and usage data from
~/.claude.cci backfill - 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-4to switch tabs, arrows to scroll,qto 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
This application is not affiliated with, endorsed by, or an official product of Anthropic.