ccboard

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

13 Interactive Tabs (TUI + Web)

Platform Capabilities

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:

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

Web Interface

Dashboard

Sessions - Browse & Live Monitoring

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):

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:

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:

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
• /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

Keybindings & Shortcuts

Keybindings

Global Navigation

List Navigation

File Operations

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:

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

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

Related Projects

• RTK (Rust Token Killer) - CLI proxy for 60-90% token reduction on dev operations
• Claude Code Ultimate Guide - Comprehensive guide to Claude Code CLI
• ccbridge - Claude Code bridge for team collaboration
• Cowork Guide - Technical coworking patterns and practices

Made with ❤️ for the Claude Code community