# ccboard
**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://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-419_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, 383 tests, 0 clippy warnings.
---
## Features
### 12 Interactive Tabs (TUI + Web)
| **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), CPU/RAM/Tokens, conversation viewer with regex search |
| **Analytics** | `3` | Advanced analytics (6 sub-views) | Budget tracking, 30-day forecast, hourly heatmap, anomaly detection, usage patterns |
| **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 |
| **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, invocation stats |
| **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 |
### Platform Capabilities
| **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 |
| **Hook Integration** | `ccboard setup` injects Claude Code hooks, live session status (Running/WaitingInput/Stopped), macOS notification on stop |
> 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.
---
## 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
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):
| **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
tar xzf ccboard-macos-x86_64.tar.gz
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
ccboard
ccboard web --port 3333
ccboard both --port 3333
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
</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 ccboard stats ccboard search "query" ccboard recent 10 ```
### 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
ccboard web --port 8080
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
- `/costs` - 4 tabs (Overview, By Model, Daily, Billing Blocks)
- `/history` - History search and filters
- `/activity` - Security audit & violations feed
- `/search` - Full-text session search
### Discover — Config Optimization
Analyze your session history to surface recurring patterns and suggest what to extract as **CLAUDE.md rules**, **skills**, or **commands**.
```bash
ccboard discover --all
ccboard discover --all --since 30d --min-count 2 --top 10
ccboard discover --top 20
ccboard discover --all --json | jq '.[0]'
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
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 ccboard export sessions --output sessions.json --format json ccboard export sessions --output sessions.md --format md ccboard export sessions --output recent.csv --since 7d ccboard export sessions --output recent.csv --since 30d ```
#### Usage statistics
```bash
ccboard export stats --output stats.csv ccboard export stats --output stats.json --format json ccboard export stats --output report.md --format md ```
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 ccboard export billing --output billing.json --format json ccboard export billing --output billing.md --format md ```
#### Single conversation
```bash
ccboard export conversation <session-id> --output conv.md 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
| 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
**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
CCBOARD_NON_INTERACTIVE=1 CCBOARD_NO_COLOR=1 CCBOARD_FORMAT=json ccboard stats
CCBOARD_CLAUDE_HOME=/tmp/test-claude ccboard stats
CCBOARD_FORMAT=json ccboard sessions search "error" | jq '.[] | .id'
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 ```
Then relaunch ccboard.
### "WASM compilation failed" (Web mode)
Ensure trunk is installed:
```bash
cargo install trunk
trunk --version ```
Then rebuild:
```bash
cd ccboard-web
trunk build --release
```
### "Connection refused" (Web mode)
Check if backend port is in use:
```bash
lsof -i :8080 netstat -ano | findstr :8080 ```
Change port if needed:
```bash
ccboard web --port 3333
```
### Linux: "File manager not opening"
Install xdg-utils:
```bash
sudo apt install xdg-utils sudo dnf install xdg-utils ```
### 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
git clone https://github.com/FlorianBruniaux/ccboard.git
cd ccboard
cargo build --all
cargo run
cargo run -- web --port 3333
RUST_LOG=ccboard=debug cargo run
```
### Testing
```bash
cargo test --all
cargo test -p ccboard-core
RUST_LOG=debug cargo test
```
### Quality Checks
```bash
cargo fmt --all
cargo clippy --all-targets
cargo fmt --all && cargo clippy --all-targets && cargo test --all
```
### Watch Mode
```bash
cargo watch -x 'run'
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)
### Related Projects
- **[RTK (Rust Token Killer)](https://github.com/FlorianBruniaux/rtk)** - CLI proxy for 60-90% token reduction on dev operations
- **[Claude Code Ultimate Guide](https://cc.bruniaux.com/)** - Comprehensive guide to Claude Code CLI
- **[ccbridge](https://ccbridge.bruniaux.com/)** - Claude Code bridge for team collaboration
- **[Cowork Guide](https://cowork.bruniaux.com/)** - Technical coworking patterns and practices
---
**Made with ❤️ for the Claude Code community**