ccboard

Florian BRUNIAUX · AI Founding Engineer @ Méthode Aristote 13 years from developer to CTO / VP Eng · Blog ↗ · Projects ↗

A free, open-source TUI/Web dashboard for Claude Code session monitoring, cost tracking & config management

The only actively-maintained, free and open-source Rust TUI combining Claude Code monitoring, Claude Code config management, hooks, agents, and MCP servers in a single 5.8MB binary. 89x faster startup with SQLite cache, 492 tests, 0 clippy warnings.

---

Features

14 Interactive Tabs (TUI + Web)

Tab	Key	Description	Highlights
Dashboard	1	Overview stats, model usage, 7-day activity	API usage estimation, plan-based budgets, MCP server count
Sessions	2	Browse all sessions with 3-pane layout	Live status icons (●/◐/✓), session type (CLI/IDE/Agent), bookmarks (b/B), subagent tree, model timeline, AI summaries (ccboard summarize), conversation viewer with regex search, code metrics (+N/-N lines), third-party sessions (Cursor [Cu], Codex [Cx], OpenCode [Oc])
Analytics	3	Advanced analytics (8 sub-views)	Budget tracking, 30-day forecast, hourly heatmap, anomaly detection (configurable thresholds), usage patterns, per-tool cost breakdown, pattern discovery (r)
Costs	4	Token analytics (6 sub-views)	Overview, By Model, Daily, Usage Periods, Top Sessions, Per Project — 4-level budget alerts
History	5	Chronological session timeline	CSV/JSON/Markdown export (x), full-text search
Audit Log	6	Security audit & violations feed	Credential detection, destructive command alerts, cross-session violations with remediation hints
MCP	7	MCP server management	Status detection (running/stopped), copy command to clipboard (y), env vars masking, usage stats by server (s)
Config	8	Cascading configuration editor	4-column diff (default/global/project/local), edit with e, reveal in file manager (o)
Hooks	9	Event-based hook management	Bash syntax highlighting, badge indicators
Tools	0	Agents, commands, and skills browser	Frontmatter YAML parsing, real invocation counts (includes session-discovered agents)
Skills	Tab cycle	Skill invocation leaderboard	Real Skill tool_use invocations only, never textual mentions; invocation/project count, tokens, estimated cost, first/last seen; [retired] badge for skills with history but no on-disk definition, resolved against local skills and installed plugin skills
Plugins	p	Plugin & capability usage analytics	Dead code detection, sort by usage/cost/name
Search	/	Full-text search across all sessions	FTS5-powered, search-as-you-type (≥2 chars), ranked snippets, opens conversation viewer
Brain	b	Cross-session knowledge base	Insights captured by session-stop hook (progress/decision/blocked/pattern/fix/context), filter by type, archive, detail pane, /ccboard-remember skill for manual entries

Platform Capabilities

Capability	Details
Performance	89x faster startup (20s → 224ms) via SQLite cache, >99% hit rate, handles 10K+ sessions
Live Updates	File watcher (500ms debounce), auto-refresh, Server-Sent Events (Web)
UX	Command palette (:), contextual help (?), vim keybindings (hjkl), breadcrumbs, scrollbar indicators, Light/Dark mode (Ctrl+T, persistent)
File Operations	Edit with $EDITOR (e), reveal in file manager (o), cross-platform
Zero Config	Works out of the box with ~/.claude, single 5.8MB binary, macOS/Linux/Windows
Multi-tool	Auto-imports sessions from Cursor, Codex CLI, and OpenCode alongside Claude Code — all parsers opt-in and silent if tool not installed
Hook Integration	ccboard setup injects Claude Code hooks, live session status (Running/WaitingInput/Stopped), macOS notification on stop, 10-min TTL pruning for stale sessions
Session Intelligence	Bookmarks with tags/notes, subagent parent/child tree, model switching timeline, LLM summaries via ccboard summarize
Brain / Knowledge Base	Session-stop hook captures progress, decisions, blockers, patterns, fixes after each meaningful session into ~/.ccboard/insights.db. Context-injection hook injects relevant past knowledge at session start. Manual entries via /ccboard-remember skill.

Missing a feature? Request it here | Found a bug? Report it

Hook-Based Live Monitoring

Run ccboard setup once to inject hooks into ~/.claude/settings.json. After that, ccboard tracks every Claude session in real time — which session is running, which is waiting for your permission, which just finished — visible in the Sessions tab with ●/◐/✓ indicators and macOS notifications.

---

StarMapper

---

Installation

Recommended: Homebrew (macOS/Linux)

brew tap FlorianBruniaux/tap
brew install ccboard

Why Homebrew? Simple one-command install, automatic updates via brew upgrade, no manual Rust setup required.

Alternative: cargo install (requires Rust 1.85+)

cargo install ccboard

Why cargo? ccboard's target audience (Claude Code users) often has Rust installed. Ensures compatibility and always installs latest crates.io version.

Note: cargo install builds the binary from crates.io source without running the WASM build step — Web UI (ccboard web) will not serve a frontend. For full Web UI support, use Homebrew, the install script, or a pre-built binary from GitHub Releases (all embed the WASM frontend at compile time).

Alternative: Install Script (macOS/Linux/Windows)

One-liner install (no Rust required):

curl -sSL https://raw.githubusercontent.com/FlorianBruniaux/ccboard/main/install.sh | bash

This script:

• Auto-detects your OS and architecture
• Downloads the latest pre-compiled binary
• Installs to ~/.local/bin (customizable with INSTALL_DIR)
• Checks if binary is in PATH

Windows users: Use Git Bash, WSL, or download manually from releases.

Alternative: Pre-built binaries (manual)

Download from GitHub Releases:

Platform	Status	Download
macOS (x86_64/ARM64)	✅ Fully tested	ccboard-macos-*.tar.gz
Linux (x86_64/ARM64)	⚠️ Community-tested	ccboard-linux-*.tar.gz
Windows (x86_64)	🧪 Experimental	ccboard-windows-*.exe.zip

Manual installation (macOS/Linux):

# Extract
tar xzf ccboard-macos-x86_64.tar.gz  # or ccboard-linux-*

# Move to PATH
mv ccboard ~/.local/bin/
chmod +x ~/.local/bin/ccboard

Manual installation (Windows):

1. Download ccboard-windows-x86_64.exe.zip
2. Extract ccboard-windows-x86_64.exe
3. Rename to ccboard.exe
4. Move to a directory in your PATH (e.g., C:\Users\YourName\.local\bin\)

Platform support:

• ✅ macOS: Manually tested on every release
• ⚠️ Linux: CI-tested, community validation welcome
• 🧪 Windows: Best-effort support (feedback appreciated)

---

Quick Start

# TUI dashboard (default)
ccboard

# Web interface
ccboard web --port 3333

# Both simultaneously
ccboard both --port 3333

# Stats only (scriptable)
ccboard stats

Navigate tabs with 1-9, 0, p. Press ? for contextual help, : to open the command palette. Refresh with r, toggle theme with Ctrl+T, quit with q. See docs/GUIDE.md for the full feature reference.

---

Screenshots

TUI (Terminal)

Dashboard - Key Metrics & Model Usage

Sessions - Project Tree & Search

Sessions - Detail View

Sessions - Live Process Monitoring

More TUI Screenshots (click to expand)

Configuration - 4-Column Merge View

Hooks Management

Agents, Commands & Skills

Cost Analytics

History Search

MCP Servers

Analytics

Audit Log

Plugins

Search

Brain — Cross-session Knowledge Base

---

Web Interface

Dashboard

Sessions - Browse & Live Monitoring

More Web Screenshots (click to expand)

Configuration

Hooks

Agents, Commands & Skills

Cost Analytics

History

MCP Servers

Analytics

---

Why ccboard Exists

Problem: Claude Code has no built-in visualization/analysis tools beyond basic CLI commands (/history, /stats). Users are left scripting with jq, grep, or manually opening JSON files.

Solution: ccboard is the only tool dedicated to Claude Code monitoring and management:

• Zero direct competitors for Claude Code dashboard (verified 2026-02-04)
• Not competing with LangSmith/W&B (they trace LangChain API calls, not local Claude sessions)
• Fills the gap between CLI commands and full observability

Unique Position

1. All-local: Reads ~/.claude files, no SaaS/API required
2. Unified Dashboard: 12 tabs (config, hooks, agents, MCP, analytics, security audit, search) vs basic CLI
3. Performance: SQLite cache (89x speedup), handles 10K+ sessions
4. Dual Interface: TUI + Web in single 5.8MB binary

Risk: Anthropic could integrate dashboard into Claude Code CLI. But currently, nothing exists.

---

Competitive Landscape

ccboard vs ccusage vs agtrace vs claudelytics — Claude Code monitoring tools compared (verified 2026-02-06):

Feature	ccboard	agtrace	claudelytics	ccusage
Status	✅ Active	✅ Active	🔴 Stale 6m	✅ Active
Stars	0	23	62	10,361
Language	Rust	Rust	Rust	TypeScript
Type	TUI+Web	TUI	TUI	CLI
TUI Dashboard	✅ 12 tabs	✅ Single view	✅ 8 tabs	❌
Config Viewer (3-level merge)	✅	❌	❌	❌
Hooks Viewer + Test	✅	❌	❌	❌
Agents/Commands/Skills Browser	✅	❌	❌	❌
MCP Server Status Detection	✅	❌	❌	❌
SQLite Cache (89x speedup)	✅	✅ Pointer-based	❌	❌
Export CSV/JSON	✅	❌	✅	✅ JSON
Live File Watcher	✅	✅ Poll 1s	❌	❌
Advanced Analytics (Forecast, Budget)	✅ 4 views	❌	⚠️ Burn rate	❌
Single Binary (no runtime)	✅ 5.8MB	✅ Rust	✅ Rust	❌ npm
MCP Server Mode	⏳ Soon	✅ 6 tools	❌	❌
Billing Blocks (5h)	✅	❌	✅	❌
Conversation Viewer	✅	❌	✅	❌
Activity Security Audit	✅	❌	❌	❌
Multi-provider	❌	✅ 3 providers	❌	❌

Unique to ccboard:

• Only multi-concern dashboard (config + hooks + agents + MCP + analytics + security audit)
• Config 3-level merge viewer (global/project/local)
• Hooks syntax highlighting + test mode
• Agents/Commands/Skills browser with invocation stats
• MCP server status detection (vs agtrace = MCP server mode)
• SQLite metadata cache (89x faster startup)
• Advanced Analytics: 30-day forecasting, budget alerts, session duration stats, usage patterns
• Activity Security Audit: credential access detection, destructive command alerts, cross-session violations feed with remediation hints
• FTS5 Search: full-text search across all sessions with ranked snippets
• Dual TUI + Web single binary

References:

• agtrace (23⭐): Observability-focused, MCP self-reflection (6 tools), multi-provider
• claudelytics (62⭐, STALE 6m): Feature-rich TUI (8 tabs, billing blocks, conversation viewer)
• ccusage (10K⭐): CLI cost tracker (reference for pricing, no dashboard)

Complementary tools:

• xlaude (171 ⭐): Git worktree manager for Claude sessions
  • Complementarity: xlaude focuses on workspace isolation (PTY sessions, branch management), ccboard on analytics/monitoring
  • Performance comparison: ccboard lazy loading 15x faster (4.8s vs 72s for 3000 sessions)
  • Use cases: Use xlaude for session isolation, ccboard for historical analysis and cost tracking
  • Learnings applied: Environment variables (QW1), message filtering (QW2), performance validation (QW3)

---

Configuration

API Usage Estimation

ccboard displays estimated API costs in the Dashboard with plan-based budget tracking. Configure your subscription plan to see accurate percentages and budget limits.

Add to ~/.claude/settings.json (global) or .claude/settings.json (per-project):

{
  "subscriptionPlan": "max20x"
}

Available plans:

Plan	Subscription Cost	Config Value
Claude Pro	$20/month	"pro"
Claude Max 5x	$50/month	"max5x"
Claude Max 20x	$200/month	"max20x"
API (Pay-as-you-go)	No fixed cost	"api"

Important: Max plans have rate limits (requests/day), not fixed spending limits. The costs shown are subscription prices used as reference points for budget estimation.

Dashboard display:

┌─ 💰 API Usage (Est.) - Claude Max 20x ─┐
│ Today:      $ 2.45 / $200.00  (  1.2%)│
│ This week:  $ 8.12 / $200.00  (  4.1%)│
│ This month: $78.40 / $200.00  ( 39.2%)│
└──────────────────────────────────────────┘

Color coding:

• 🟢 Green: < 60% of monthly budget
• 🟡 Yellow: 60-80% of monthly budget
• 🔴 Red: > 80% of monthly budget

Note: This is a local estimation calculated from your billing blocks, not real-time API data. For actual limits, use :usage in Claude Code or the Anthropic dashboard.

Budget Alerts & Tracking

Configure custom monthly budgets with automatic alerts in the Analytics tab (Tab 9 → Overview). Get visual warnings when approaching your spending limit.

Add to ~/.claude/settings.json (global) or .claude/settings.json (per-project):

{
  "budget": {
    "monthlyBudgetUsd": 50.0,
    "alertThresholdPct": 80.0
  }
}

Configuration:

Field	Type	Description	Default
monthlyBudgetUsd	number	Your monthly spending limit in USD	Required
alertThresholdPct	number	Alert threshold percentage (0-100)	80.0

Analytics Overview display:

┌─ Budget Status ─────────────────────────────┐
│ Monthly Est: $42.50                         │
│ Budget:      $50.00  ━━━━━━━━━━━━━━━━  85% │
│ Remaining:   $7.50 (15%)                    │
│                                              │
│ ⚠️  WARNING: Approaching budget limit (85%) │
│ 💡 TIP: Projected overage: $5.20 if trend…  │
└──────────────────────────────────────────────┘

Visual indicators:

• 🟢 Green bar: < 60% of budget (safe zone)
• 🟡 Yellow bar: 60-80% of budget (caution)
• 🔴 Red bar + ⚠️: ≥ 80% of budget (warning)

Alert types:

1. Budget Warning: Current cost approaching threshold
2. Projected Overage: Forecast predicts budget exceeded if trend continues
3. Usage Spike: Daily tokens > 2x average (anomaly detection)

4-level priority (higher overrides lower):

1. ~/.claude/settings.json (global)
2. ~/.claude/settings.local.json (global, not committed to git)
3. .claude/settings.json (project, committed)
4. .claude/settings.local.json (project, developer-specific)

Example workflows:

• Solo developer: Set global budget in ~/.claude/settings.json
• Team project: Set team budget in .claude/settings.json (committed), override personally in .claude/settings.local.json
• Multiple projects: Different budgets per project in each .claude/settings.json

---

Usage

TUI Mode (Default)

ccboard              # Launch TUI dashboard
ccboard stats        # Print stats and exit
ccboard search "query"   # Search sessions
ccboard recent 10    # Show 10 most recent sessions

Web Mode

ccboard has 2 web workflows depending on your use case:

Option 1: Production (Single Command) ⭐ Recommended

For: Running the full stack (API + Frontend) in production or for general use.

ccboard web

Output:

⠋ Loading sessions and statistics...
✓ Ready in 2.34s (1,247 sessions loaded)

🌐 Backend API + Frontend: http://127.0.0.1:3333
   API endpoints:          http://127.0.0.1:3333/api/*

Features:

• ✅ Single process, single port
• ✅ WASM frontend embedded in the binary (no separate build step)
• ✅ Real-time data updates via Server-Sent Events (SSE)
• ❌ No hot reload (requires trunk build + F5 after code changes when developing)

When to use: Daily use, demos, production, or when you just want the web interface running.

---

Option 2: Development (Hot Reload) 🔧

For: Developing the frontend with automatic recompilation and browser refresh.

# Terminal 1: Start backend API
ccboard web --port 8080

# Terminal 2: Start frontend dev server (run in ccboard repo root)
trunk serve --port 3333

Output Terminal 1:

🌐 Backend API only:       http://127.0.0.1:8080/api/*
   💡 Run 'trunk build' to compile frontend

Output Terminal 2:

📦 Starting build...
✅ Success! App is being served at: http://127.0.0.1:3333

Features:

• ✅ Real-time data updates via SSE
• ✅ Hot reload: Frontend code changes auto-recompile and refresh browser
• ✅ Separate logs for backend and frontend
• ❌ Two terminals required

When to use: When developing the Leptos frontend (editing crates/ccboard-web/src/**/*.rs).

Note: trunk serve automatically proxies /api/* requests to http://localhost:8080 via Trunk.toml config.

---

Dual Mode (TUI + Web)

Run both TUI and web server simultaneously:

ccboard both --port 3333

• Web server runs in background
• TUI runs in foreground
• Shared DataStore (same data, live updates)
• Press q in TUI to exit both

Web Pages

Available Pages (100% TUI parity) ✅:

• / - Dashboard with KPIs and forecast
• /sessions - Sessions browser with live CPU/RAM monitoring 🔥
• /analytics - Analytics with budget tracking
• /config - 4-column configuration viewer
• /hooks - Hooks with syntax highlighting
• /mcp - MCP servers with status
• /agents - Agents/Commands/Skills browser
• /skills - Skill invocation leaderboard with [retired] badge
• /costs - 4 tabs (Overview, By Model, Daily, Billing Blocks)
• /history - History search and filters
• /activity - Security audit & violations feed
• /search - Full-text session search

Session Summaries

Generate and cache an AI summary of any session using claude --print:

# Generate summary (cached to ~/.ccboard/summaries/<id>.md)
ccboard summarize <session-id>

# Regenerate even if cached
ccboard summarize <session-id> --force

# Use a specific model
ccboard summarize <session-id> --model claude-haiku-4-5

Once cached, the summary appears automatically in the Sessions detail pane under AI Summary. Summaries are plain-text, under 200 words, and cover what was accomplished and key decisions.

Discover — Config Optimization

Analyze your session history to surface recurring patterns and suggest what to extract as CLAUDE.md rules, skills, or commands.

# Analyze all projects, last 90 days (default)
ccboard discover --all

# Last 30 days, lower threshold, top 10
ccboard discover --all --since 30d --min-count 2 --top 10

# Current project only
ccboard discover --top 20

# JSON output (pipe to jq)
ccboard discover --all --json | jq '.[0]'

# Semantic analysis via Claude (requires claude in PATH)
ccboard discover --all --llm

Output example:

ccboard discover — 1121 sessions · 42 project(s) · since 90d

📋  CLAUDE.MD RULE
────────────────────────────────────────────────────────────
write tests before implementation                          [cross-project]
  234 sessions (28%) · 891 occurrences · score 0.416
  → 3a72f1c4-...

🧩  SKILL
────────────────────────────────────────────────────────────
security review authentication flow
  71 sessions (8%) · 203 occurrences · score 0.084

⚡  COMMAND
────────────────────────────────────────────────────────────
generate prisma migration rollback
  18 sessions (2%) · 44 occurrences · score 0.021

Categories assigned automatically: >20% of sessions → CLAUDE.md rule, ≥5% → skill, else → command. Cross-project patterns get a 1.5× score bonus.

Stats Only

# Print stats summary and exit
ccboard stats

Output example:

ccboard - Claude Code Statistics
================================

Total Tokens:     12.5M
  Input:          8.2M
  Output:         3.1M
  Cache Read:     890K
  Cache Write:    310K

Sessions:         2,340
Messages:         18,450
Cache Hit Ratio:  28.7%

Models:
  claude-sonnet-4.5: 9.8M tokens (in: 6.5M, out: 2.3M)
  claude-opus-4: 1.2M tokens (in: 800K, out: 400K)

Export

Export data to CSV, JSON, or Markdown for external analysis, BI tools, or sharing.

Sessions list

ccboard export sessions --output sessions.csv                     # CSV (default)
ccboard export sessions --output sessions.json --format json      # JSON
ccboard export sessions --output sessions.md --format md          # Markdown table
ccboard export sessions --output recent.csv --since 7d            # Last 7 days only
ccboard export sessions --output recent.csv --since 30d           # Last 30 days

Usage statistics

ccboard export stats --output stats.csv                           # Per-model breakdown CSV
ccboard export stats --output stats.json --format json            # Full StatsCache JSON
ccboard export stats --output report.md --format md               # Human-readable report

The Markdown report includes: totals (tokens/sessions/messages/cache ratio), per-model table, and last 30 days of daily activity.

Billing blocks

ccboard export billing --output billing.csv                       # CSV (default)
ccboard export billing --output billing.json --format json        # JSON with full token breakdown
ccboard export billing --output billing.md --format md            # Markdown table

Single conversation

ccboard export conversation <session-id> --output conv.md         # Markdown (default)
ccboard export conversation <session-id> --output conv.json --format json
ccboard export conversation <session-id> --output conv.html --format html

Report (CI/CD)

Generate a usage report with optional CI quality gates. Exits with code 1 when a gate is exceeded, so you can plug it directly into GitHub Actions, GitLab CI, or any shell script.

# Markdown report, last 7 days (default)
ccboard report

# JSON for machine parsing
ccboard report --format json

# HTML with embedded charts
ccboard report --format html --output report.html

# Last 30 days
ccboard report --since 30d

# Write to file
ccboard report --output weekly-report.md

# Fail CI if token budget exceeded
ccboard report --budget 500000

# Fail CI if error rate > 5%
ccboard report --error-threshold 5

# Combine gates
ccboard report --budget 1000000 --error-threshold 10 --since 30d

Output example (Markdown):

# ccboard Report

**Period:** last 7d
**Generated:** 2026-06-24 15:13 UTC

## Summary

| Metric | Value |
|--------|-------|
| Total Tokens | 14.49B |
| Sessions (period) | 1441 |
| Est. Cost | $54622.19 |
| Error Rate | 0.0% |
| Cache Hit Ratio | 99.9% |

## Top Tools by Token Usage

| Tool | Calls | Tokens | % of Total | Est. Cost |
|------|-------|--------|------------|-----------|
| Bash | 14050 | 1.46B | 47.6% | $26026.22 |
| Read | 7475 | 677M | 22.1% | $12083.00 |
| Edit | 3825 | 459M | 15.0% | $8205.99 |
...

CI gate behavior:

• --budget and --error-threshold can be combined
• Exit code 0 when all gates pass, exit code 1 when any gate fails
• Report is always printed to stdout (or --output file) regardless of gate result
• Error details go to stderr so stdout remains parseable

Skills (invocation leaderboard)

Exact counts of real Skill invocations (the Skill tool_use block), never textual mentions of a skill's name in a message.

# Full leaderboard, table output
ccboard skills

# JSON for scripting
ccboard skills --json

# Include subagent-driven invocations
ccboard skills --include-subagents

# Filter by time window or project
ccboard skills --since 30d
ccboard skills --project ccboard

# Detail for a single skill
ccboard skills flow-lean

---

Keybindings & Shortcuts

Keybindings

Global Navigation

Key	Action
q	Quit application
Tab / Shift+Tab	Navigate tabs forward/backward
1-9	Jump to specific tab
:	Open command palette
r	Refresh data
Esc	Close popup / Go back

List Navigation

Key	Action
j / ↓	Move down
k / ↑	Move up
h / ←	Move left / Collapse
l / →	Move right / Expand
PgUp / PgDn	Page up/down (10 items)
Enter	Show detail / Select

File Operations

Key	Action
e	Edit file in $EDITOR
o	Reveal file in file manager

Tab-Specific

Sessions

• / - Search sessions
• Enter - Show session detail
• b - Toggle bookmark on selected session
• B - Toggle "bookmarked only" filter
• s - Cycle sort mode (date/tokens/duration/messages)

Config

• m - Show MCP detail modal
• e - Edit config file (based on column focus)

History

• / - Full-text search across sessions

Costs

• Tab / ← / → - Switch cost views (Overview/By Model/Daily)

Activity (Tab/Shift+Tab to reach)

• r - Batch-scan all sessions (4 concurrent)
• Enter - Analyze selected session individually
• Tab - Toggle Sessions ↔ Violations view
• j/k - Navigate sessions or violations list

Search (Tab/Shift+Tab to reach)

• Type to search — FTS5 full-text search across all sessions
• Results ranked by relevance with highlighted snippets

Environment Variables

ccboard supports environment variables for automation and CI/CD workflows:

Variable	Description	Example
CCBOARD_CLAUDE_HOME	Override Claude home directory	CCBOARD_CLAUDE_HOME=/custom/path ccboard stats
CCBOARD_NON_INTERACTIVE	Disable interactive prompts (CI/CD mode)	CCBOARD_NON_INTERACTIVE=1 ccboard stats
CCBOARD_FORMAT	Force output format: json or table	CCBOARD_FORMAT=json ccboard recent 10
CCBOARD_NO_COLOR	Disable ANSI colors (log-friendly)	CCBOARD_NO_COLOR=1 ccboard search "bug"

Use cases:

# CI/CD: JSON output without colors
CCBOARD_NON_INTERACTIVE=1 CCBOARD_NO_COLOR=1 CCBOARD_FORMAT=json ccboard stats

# Testing: Isolated configuration
CCBOARD_CLAUDE_HOME=/tmp/test-claude ccboard stats

# Automation: Pipe JSON to other tools
CCBOARD_FORMAT=json ccboard sessions search "error" | jq '.[] | .id'

# Log-friendly: No colors for file redirects
CCBOARD_NO_COLOR=1 ccboard recent 50 > sessions.log

Command Palette

Press : to open the command palette with fuzzy matching:

:dashboard    → Jump to Dashboard tab
:sessions     → Jump to Sessions tab
:config       → Jump to Config tab
:mcp          → Jump to MCP tab
:quit         → Exit application

File Editing

ccboard integrates with your configured editor:

1. Navigate to any file (agent, session, hook, config)
2. Press e to edit
3. Editor opens in terminal (terminal state preserved)
4. Changes detected automatically via file watcher

Editor priority: $VISUAL > $EDITOR > fallback (nano/notepad.exe)

---

Troubleshooting

"Stats not loading" or "No sessions found"

Run Claude Code at least once to generate ~/.claude directory:

claude  # Or use Claude Code via IDE

Then relaunch ccboard.

"WASM compilation failed" (Web mode)

Ensure trunk is installed:

cargo install trunk
trunk --version  # Should be 0.18+

Then rebuild:

cd ccboard-web
trunk build --release

"Connection refused" (Web mode)

Check if backend port is in use:

lsof -i :8080  # macOS/Linux
netstat -ano | findstr :8080  # Windows

Change port if needed:

ccboard web --port 3333

Linux: "File manager not opening"

Install xdg-utils:

sudo apt install xdg-utils  # Debian/Ubuntu
sudo dnf install xdg-utils  # Fedora

Windows: Terminal rendering issues

Use Windows Terminal (not cmd.exe) for proper Unicode support:

• Download: Windows Terminal
• Braille spinners ⠋⠙⠹ render correctly in Windows Terminal

---

Development

Stack

ccboard/                     # Binary CLI entry point
├── ccboard-core/            # Data layer (parsers, models, store, watcher)
├── ccboard-tui/             # Ratatui frontend (12 tabs)
└── ccboard-web/             # Axum API backend + Leptos WASM frontend

Dependency flow: ccboard → ccboard-tui + ccboard-web → ccboard-core

Core principles: Single binary with dual frontends sharing a thread-safe DataStore. Graceful degradation (partial data if files corrupted/missing). SQLite metadata cache (89x speedup) with lazy content loading. Arc for sessions (50x memory reduction), parking_lot::RwLock for stats/settings.

For detailed architecture documentation, see ARCHITECTURE.md.

Prerequisites

• Rust 1.85+ (rustup install stable)
• Claude Code with ~/.claude directory

Build & Run

# Clone repository
git clone https://github.com/FlorianBruniaux/ccboard.git
cd ccboard

# Build all crates
cargo build --all

# Run TUI (default)
cargo run

# Run web interface
cargo run -- web --port 3333

# Run with debug logging
RUST_LOG=ccboard=debug cargo run

Testing

# Run all tests (383 tests)
cargo test --all

# Run tests for specific crate
cargo test -p ccboard-core

# Run with logging
RUST_LOG=debug cargo test

Quality Checks

# Format code (REQUIRED before commit)
cargo fmt --all

# Clippy (MUST pass with zero warnings)
cargo clippy --all-targets

# Pre-commit checklist
cargo fmt --all && cargo clippy --all-targets && cargo test --all

Watch Mode

# Auto-rebuild TUI on changes
cargo watch -x 'run'

# Auto-rebuild web
cargo watch -x 'run -- web'

Error Handling Standards

ccboard follows strict Rust error handling practices:

• anyhow::Result in binaries (ccboard, ccboard-tui, ccboard-web)
• thiserror for custom errors in ccboard-core
• Always use .context("description") with ? operator
• No unwrap() in production code (tests only)
• Graceful degradation: Return Option<T> + populate LoadReport

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Development workflow:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Make changes with tests
4. Run quality checks (cargo fmt && cargo clippy && cargo test)
5. Commit with descriptive message
6. Push and open a Pull Request

---

Roadmap & Documentation

Current Status: 🎉 PRODUCTION-READY

Completed ✅

• ✅ Infrastructure: Stats parser, Settings merge, Session metadata, DataStore, SQLite cache (89x speedup)
• ✅ TUI Dashboard: 12 interactive tabs with full keybinding navigation
• ✅ Web Frontend: Full Leptos/WASM UI with 100% TUI parity (12 pages)
• ✅ Live Monitoring: CPU/RAM/Tokens tracking for active Claude processes via hook injection
• ✅ Cost Analytics: 6 views (Overview, By Model, Daily, Usage Periods, Top Sessions, Per Project) + 4-level budget alerts
• ✅ Advanced Analytics: 30-day forecasting, hourly heatmap, anomaly detection, usage patterns, actionable insights
• ✅ Conversation Viewer: Full JSONL replay with regex search (/ + n/N), syntax highlighting, HTML export
• ✅ Dynamic Pricing: LiteLLM integration with automatic price updates and local caching
• ✅ Export Features: CSV/JSON/Markdown export for sessions, stats, billing, conversations
• ✅ Activity Security Audit: Per-session tool audit, credential detection, destructive command alerts, remediation hints
• ✅ Search Tab: FTS5 full-text search across all sessions, search-as-you-type, ranked snippets
• ✅ Discover: N-gram analysis across session history to suggest CLAUDE.md rules, skills, and commands
• ✅ Tool Cost Analytics: Per-tool token tracking, tool chain analysis, cost suggestions engine
• ✅ Plugin Analytics: Skill/MCP/agent usage, dead code detection

Total: 419 tests passing, 0 clippy warnings

For detailed version history, see CHANGELOG.md.

Documentation

Document	Description
User Guide	Complete feature reference: all tabs, keybindings, CLI, tips
ARCHITECTURE.md	Technical architecture, data flow, concurrency model
CHANGELOG.md	Version history with detailed change descriptions
SECURITY.md	Security policy, vulnerability reporting, best practices
CROSS_PLATFORM.md	Platform-specific considerations and validation
CONTRIBUTING.md	Development guidelines and contribution workflow
API Documentation	REST API and SSE endpoints for Web UI
Architecture Decision Records	Key architectural decisions and their rationale
Architecture Decision Records	Key architectural decisions and their rationale

---

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

---

Acknowledgments

This project was developed following Test-Driven Development (TDD) principles with guidance from Agent Academy.

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com

---

Author

Florian Bruniaux - Independent Developer 🌐 florian.bruniaux.com | 💼 LinkedIn | 🐙 GitHub

---

Links

Project

• Repository: https://github.com/FlorianBruniaux/ccboard
• Issues: https://github.com/FlorianBruniaux/ccboard/issues
• Releases: https://github.com/FlorianBruniaux/ccboard/releases
• Crates.io: https://crates.io/crates/ccboard
• Documentation: User Guide | CHANGELOG.md

Explore the ecosystem

These projects extend the workflow without duplicating this tool:

• Search with CC-Sessions: move from the dashboard to a focused CLI search of local history.
• Measure with cc-skill-usage: add a specialist analysis of real skill invocations.
• Learn with Claude Code Ultimate Guide: connect observed signals to the guide's observability practices.
• Route with CC-Copilot Bridge: observe sessions whose model provider can be selected through the bridge.

Browse the complete open-source galaxy

---

Made with ❤️ for the Claude Code community