ccboard
Monitor Claude Code sessions, costs, config, hooks, agents & MCP servers from a single Rust binary — TUI (9 tabs) + Web interface with live process tracking, budget alerts, and 30-day forecasting
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/florianbruniaux--ccboard)HTML
<a href="/listings/florianbruniaux--ccboard"><img src="/api/listings/florianbruniaux--ccboard/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
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](https://github.com/FlorianBruniaux/ccboard/releases/latest):
| Platform | Status | Download | |----------|--------|----------| | **macOS** (x86_64/ARM64) | ✅ Fully tested | [ccboard-macos-*.tar.gz](https://github.com/FlorianBruniaux/ccboard/releases) | | **Linux** (x86_64/ARM64) | ⚠️ Community-tested | [ccboard-linux-*.tar.gz](https://github.com/FlorianBruniaux/ccboard/releases) | | **Windows** (x86_64) | 🧪 Experimental | [ccboard-windows-*.exe.zip](https://github.com/FlorianBruniaux/ccboard/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)
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 16 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "ccboard-marketplace",
- "version": "0.1.0",
- "description": "Claude Code dashboard and monitoring tools",
- "plugins": [
- {
- "name": "ccboard",
- "path": "skills/ccboard",
- "description": "Comprehensive TUI/Web dashboard for Claude Code",
- "version": "0.1.0",
- "author": "Florian Bruniaux",
- "keywords": ["dashboard", "monitoring", "tui", "mcp", "sessions", "costs"],
- "categories": ["productivity", "development-tools"]
- }
- ]
- }
README.md · README · 1,181 lines · 1 finding marked
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # ccboard
- <table>
- <tr>
- <td width="64">
- <a href="https://www.florian.bruniaux.com/about/?utm_source=github&utm_medium=readme&utm_campaign=ccboard"><img src="https://cc.bruniaux.com/author.png" width="56" height="56" alt="Florian Bruniaux" /></a>
- </td>
- <td>
- <strong><a href="https://www.florian.bruniaux.com/about/?utm_source=github&utm_medium=readme&utm_campaign=ccboard">Florian BRUNIAUX</a></strong> · AI Founding Engineer @ <a href="https://methode-aristote.fr/">Méthode Aristote</a><br />
- 13 years from developer to CTO / VP Eng · <a href="https://www.florian.bruniaux.com/blog/?utm_source=github&utm_medium=readme&utm_campaign=ccboard">Blog ↗</a> · <a href="https://www.florian.bruniaux.com/projects/?utm_source=github&utm_medium=readme&utm_campaign=ccboard">Projects ↗</a>
- </td>
- </tr>
- </table>
- **A free, open-source TUI/Web dashboard for Claude Code session monitoring, cost tracking & config management**
- <p align="center">
- <a href="https://github.com/FlorianBruniaux/ccboard/stargazers"><img src="https://img.shields.io/github/stars/FlorianBruniaux/ccboard?style=for-the-badge" alt="GitHub stars"/></a>
- <a href="https://starmapper.bruniaux.com/FlorianBruniaux/ccboard"><img src="https://starmapper.bruniaux.com/api/badge/FlorianBruniaux/ccboard" alt="StarMapper"/></a>
- <a href="https://crates.io/crates/ccboard"><img src="https://img.shields.io/crates/v/ccboard?style=for-the-badge&logo=rust" alt="crates.io"/></a>
- <a href="https://crates.io/crates/ccboard"><img src="https://img.shields.io/crates/d/ccboard?style=for-the-badge" alt="Downloads"/></a>
- </p>
- <p align="center">
- <img src="https://img.shields.io/badge/Tests-492_passing-success?style=for-the-badge&logo=github-actions" alt="Tests"/>
- <img src="https://img.shields.io/badge/Clippy-0_warnings-success?style=for-the-badge&logo=rust" alt="Clippy"/>
- <img src="https://img.shields.io/badge/Binary-5.8MB-blue?style=for-the-badge" alt="Binary Size"/>
- <img src="https://img.shields.io/badge/Cache_Speedup-89x-orange?style=for-the-badge&logo=sqlite" alt="Speedup"/>
- </p>
- <p align="center">
- <a href="./LICENSE-MIT"><img src="https://img.shields.io/badge/License-MIT_OR_Apache--2.0-blue.svg?style=flat-square" alt="License"/></a>
- <a href="https://github.com/FlorianBruniaux/ccboard/actions"><img src="https://img.shields.io/github/actions/workflow/status/FlorianBruniaux/ccboard/ci.yml?branch=main&style=flat-square&logo=github-actions" alt="CI"/></a>
- <a href="https://www.rust-lang.org/"><img src="https://img.shields.io/badge/rust-1.85%2B-orange.svg?style=flat-square&logo=rust" alt="Rust"/></a>
- <a href="#installation"><img src="https://img.shields.io/badge/platform-macOS_|_Linux_|_Windows-lightgrey?style=flat-square" alt="Platform"/></a>
- </p>
- <p align="center">
- <img src="assets/demo.gif" alt="ccboard demo" width="800"/>
- </p>
- > **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](https://github.com/FlorianBruniaux/ccboard/issues/new?template=feature_request.yml) | Found a bug? [Report it](https://github.com/FlorianBruniaux/ccboard/issues/new?template=bug_report.yml)
- ### 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
- <p align="center">
- <a href="https://starmapper.bruniaux.com/FlorianBruniaux/ccboard">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://starmapper.bruniaux.com/api/map-image/FlorianBruniaux/ccboard?theme=dark" />
- <source media="(prefers-color-scheme: light)" srcset="https://starmapper.bruniaux.com/api/map-image/FlorianBruniaux/ccboard?theme=light" />
- <img alt="StarMapper — see who stars this repo on a world map" src="https://starmapper.bruniaux.com/api/map-image/FlorianBruniaux/ccboard" />
- </picture>
- </a>
- </p>
- ---
- ## Installation
- ### Recommended: Homebrew (macOS/Linux)
- ```bash
- 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+)
- ```bash
- 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):
- ```bash
- curl -sSL https://raw.githubusercontent.com/FlorianBruniaux/ccboard/main/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 128 on GitHub
- ```
- 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](https://github.com/FlorianBruniaux/ccboard/releases/latest):
- | Platform | Status | Download |
- |----------|--------|----------|
- | **macOS** (x86_64/ARM64) | ✅ Fully tested | [ccboard-macos-*.tar.gz](https://github.com/FlorianBruniaux/ccboard/releases) |
- | **Linux** (x86_64/ARM64) | ⚠️ Community-tested | [ccboard-linux-*.tar.gz](https://github.com/FlorianBruniaux/ccboard/releases) |
- | **Windows** (x86_64) | 🧪 Experimental | [ccboard-windows-*.exe.zip](https://github.com/FlorianBruniaux/ccboard/releases) |
- **Manual installation** (macOS/Linux):
- ```bash
- # 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
- ```bash
- # 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](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
- 
- <details>
- <summary>More TUI Screenshots (click to expand)</summary>
- #### 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
- 
- </details>
- ---
- ### Web Interface
- #### Dashboard
- 
- #### Sessions - Browse & Live Monitoring
- 
- 
- <details>
- <summary>More Web Screenshots (click to expand)</summary>
- #### Configuration
- 
- 
- #### Hooks
- 
- #### Agents, Commands & Skills
- 
- 
- 
- #### Cost Analytics
- 
- 
- 
- 
- #### History
- 
- #### MCP Servers
- 
- #### Analytics
- 
- 
- 
- 
- </details>
- ---
- ## 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](https://github.com/Xuanwo/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):
- ```json
- {
- "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):
- ```json
- {
- "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)
- ```bash
- 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.
- ```bash
- 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.
- ```bash
- # 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:
- ```bash
- 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`:
- ```bash
- # 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**.
- ```bash
- # 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
- ```bash
- # 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
- ```bash
- 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
- ```bash
- 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
- ```bash
- 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
- ```bash
- 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.
- ```bash
- # 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):**
- ```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.
- ```bash
- # 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**:
- ```bash
- # 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:
- ```bash
- claude # Or use Claude Code via IDE
- ```
- Then relaunch ccboard.
- ### "WASM compilation failed" (Web mode)
- Ensure trunk is installed:
- ```bash
- cargo install trunk
- trunk --version # Should be 0.18+
- ```
- Then rebuild:
- ```bash
- cd ccboard-web
- trunk build --release
- ```
- ### "Connection refused" (Web mode)
- Check if backend port is in use:
- ```bash
- lsof -i :8080 # macOS/Linux
- netstat -ano | findstr :8080 # Windows
- ```
- Change port if needed:
- ```bash
- ccboard web --port 3333
- ```
- ### Linux: "File manager not opening"
- Install xdg-utils:
- ```bash
- 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](https://aka.ms/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](ARCHITECTURE.md).
- ### Prerequisites
- - Rust 1.85+ (`rustup install stable`)
- - Claude Code with `~/.claude` directory
- ### Build & Run
- ```bash
- # 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
- ```bash
- # 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
- ```bash
- # 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
- ```bash
- # 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](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](CHANGELOG.md).
- ### Documentation
- | Document | Description |
- |----------|-------------|
- | [User Guide](docs/GUIDE.md) | Complete feature reference: all tabs, keybindings, CLI, tips |
- | [ARCHITECTURE.md](ARCHITECTURE.md) | Technical architecture, data flow, concurrency model |
- | [CHANGELOG.md](CHANGELOG.md) | Version history with detailed change descriptions |
- | [SECURITY.md](SECURITY.md) | Security policy, vulnerability reporting, best practices |
- | [CROSS_PLATFORM.md](CROSS_PLATFORM.md) | Platform-specific considerations and validation |
- | [CONTRIBUTING.md](CONTRIBUTING.md) | Development guidelines and contribution workflow |
- | [API Documentation](docs/API.md) | REST API and SSE endpoints for Web UI |
- | [Architecture Decision Records](docs/architecture/) | Key architectural decisions and their rationale |
- | [Architecture Decision Records](docs/architecture/) | Key architectural decisions and their rationale |
- ---
- ## License
- Licensed under either of:
- - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- - MIT License ([LICENSE-MIT](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](https://florian.bruniaux.com/) | 💼 [LinkedIn](https://www.linkedin.com/in/florianbruniaux/) | 🐙 [GitHub](https://github.com/FlorianBruniaux)
- ---
- ## 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](docs/GUIDE.md) | [CHANGELOG.md](CHANGELOG.md)
- <!-- BEGIN GENERATED RELATED PROJECTS -->
- <!-- Source: https://github.com/FlorianBruniaux/FlorianBruniaux/blob/main/ecosystem/projects.json; project: ccboard -->
- ## Explore the ecosystem
- These projects extend the workflow without duplicating this tool:
- - **Search with [CC-Sessions](https://github.com/FlorianBruniaux/cc-sessions)**: move from the dashboard to a focused CLI search of local history.
- - **Measure with [cc-skill-usage](https://github.com/FlorianBruniaux/cc-skill-usage)**: add a specialist analysis of real skill invocations.
- - **Learn with [Claude Code Ultimate Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)**: connect observed signals to the guide's observability practices.
- - **Route with [CC-Copilot Bridge](https://github.com/FlorianBruniaux/cc-copilot-bridge)**: observe sessions whose model provider can be selected through the bridge.
- [Browse the complete open-source galaxy](https://github.com/FlorianBruniaux#open-source-galaxy)
- <!-- END GENERATED RELATED PROJECTS -->
- ---
- **Made with ❤️ for the Claude Code community**
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.