Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/florianbruniaux--ccboard/badge.svg)](/listings/florianbruniaux--ccboard)

HTML

<a href="/listings/florianbruniaux--ccboard"><img src="/api/listings/florianbruniaux--ccboard/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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)

  1. {
  2. "name": "ccboard-marketplace",
  3. "version": "0.1.0",
  4. "description": "Claude Code dashboard and monitoring tools",
  5. "plugins": [
  6. {
  7. "name": "ccboard",
  8. "path": "skills/ccboard",
  9. "description": "Comprehensive TUI/Web dashboard for Claude Code",
  10. "version": "0.1.0",
  11. "author": "Florian Bruniaux",
  12. "keywords": ["dashboard", "monitoring", "tui", "mcp", "sessions", "costs"],
  13. "categories": ["productivity", "development-tools"]
  14. }
  15. ]
  16. }
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)

  1. # ccboard
  2. <table>
  3. <tr>
  4. <td width="64">
  5. <a href="https://www.florian.bruniaux.com/about/?utm_source=github&amp;utm_medium=readme&amp;utm_campaign=ccboard"><img src="https://cc.bruniaux.com/author.png" width="56" height="56" alt="Florian Bruniaux" /></a>
  6. </td>
  7. <td>
  8. <strong><a href="https://www.florian.bruniaux.com/about/?utm_source=github&amp;utm_medium=readme&amp;utm_campaign=ccboard">Florian BRUNIAUX</a></strong> &middot; AI Founding Engineer @ <a href="https://methode-aristote.fr/">Méthode Aristote</a><br />
  9. 13 years from developer to CTO / VP Eng &middot; <a href="https://www.florian.bruniaux.com/blog/?utm_source=github&amp;utm_medium=readme&amp;utm_campaign=ccboard">Blog &#8599;</a> &middot; <a href="https://www.florian.bruniaux.com/projects/?utm_source=github&amp;utm_medium=readme&amp;utm_campaign=ccboard">Projects &#8599;</a>
  10. </td>
  11. </tr>
  12. </table>
  13. **A free, open-source TUI/Web dashboard for Claude Code session monitoring, cost tracking & config management**
  14. <p align="center">
  15. <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>
  16. <a href="https://starmapper.bruniaux.com/FlorianBruniaux/ccboard"><img src="https://starmapper.bruniaux.com/api/badge/FlorianBruniaux/ccboard" alt="StarMapper"/></a>
  17. <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>
  18. <a href="https://crates.io/crates/ccboard"><img src="https://img.shields.io/crates/d/ccboard?style=for-the-badge" alt="Downloads"/></a>
  19. </p>
  20. <p align="center">
  21. <img src="https://img.shields.io/badge/Tests-492_passing-success?style=for-the-badge&logo=github-actions" alt="Tests"/>
  22. <img src="https://img.shields.io/badge/Clippy-0_warnings-success?style=for-the-badge&logo=rust" alt="Clippy"/>
  23. <img src="https://img.shields.io/badge/Binary-5.8MB-blue?style=for-the-badge" alt="Binary Size"/>
  24. <img src="https://img.shields.io/badge/Cache_Speedup-89x-orange?style=for-the-badge&logo=sqlite" alt="Speedup"/>
  25. </p>
  26. <p align="center">
  27. <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>
  28. <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>
  29. <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>
  30. <a href="#installation"><img src="https://img.shields.io/badge/platform-macOS_|_Linux_|_Windows-lightgrey?style=flat-square" alt="Platform"/></a>
  31. </p>
  32. <p align="center">
  33. <img src="assets/demo.gif" alt="ccboard demo" width="800"/>
  34. </p>
  35. > **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.
  36. ---
  37. ## Features
  38. ### 14 Interactive Tabs (TUI + Web)
  39. | Tab | Key | Description | Highlights |
  40. |-----|-----|-------------|------------|
  41. | **Dashboard** | `1` | Overview stats, model usage, 7-day activity | API usage estimation, plan-based budgets, MCP server count |
  42. | **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]`) |
  43. | **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`) |
  44. | **Costs** | `4` | Token analytics (6 sub-views) | Overview, By Model, Daily, Usage Periods, Top Sessions, Per Project — 4-level budget alerts |
  45. | **History** | `5` | Chronological session timeline | CSV/JSON/Markdown export (`x`), full-text search |
  46. | **Audit Log** | `6` | Security audit & violations feed | Credential detection, destructive command alerts, cross-session violations with remediation hints |
  47. | **MCP** | `7` | MCP server management | Status detection (running/stopped), copy command to clipboard (`y`), env vars masking, usage stats by server (`s`) |
  48. | **Config** | `8` | Cascading configuration editor | 4-column diff (default/global/project/local), edit with `e`, reveal in file manager (`o`) |
  49. | **Hooks** | `9` | Event-based hook management | Bash syntax highlighting, badge indicators |
  50. | **Tools** | `0` | Agents, commands, and skills browser | Frontmatter YAML parsing, real invocation counts (includes session-discovered agents) |
  51. | **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 |
  52. | **Plugins** | `p` | Plugin & capability usage analytics | Dead code detection, sort by usage/cost/name |
  53. | **Search** | `/` | Full-text search across all sessions | FTS5-powered, search-as-you-type (≥2 chars), ranked snippets, opens conversation viewer |
  54. | **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 |
  55. ### Platform Capabilities
  56. | Capability | Details |
  57. |-----------|---------|
  58. | **Performance** | 89x faster startup (20s → 224ms) via SQLite cache, >99% hit rate, handles 10K+ sessions |
  59. | **Live Updates** | File watcher (500ms debounce), auto-refresh, Server-Sent Events (Web) |
  60. | **UX** | Command palette (`:`), contextual help (`?`), vim keybindings (hjkl), breadcrumbs, scrollbar indicators, Light/Dark mode (`Ctrl+T`, persistent) |
  61. | **File Operations** | Edit with `$EDITOR` (`e`), reveal in file manager (`o`), cross-platform |
  62. | **Zero Config** | Works out of the box with `~/.claude`, single 5.8MB binary, macOS/Linux/Windows |
  63. | **Multi-tool** | Auto-imports sessions from Cursor, Codex CLI, and OpenCode alongside Claude Code — all parsers opt-in and silent if tool not installed |
  64. | **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 |
  65. | **Session Intelligence** | Bookmarks with tags/notes, subagent parent/child tree, model switching timeline, LLM summaries via `ccboard summarize` |
  66. | **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. |
  67. > 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)
  68. ### Hook-Based Live Monitoring
  69. 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.
  70. ---
  71. ## StarMapper
  72. <p align="center">
  73. <a href="https://starmapper.bruniaux.com/FlorianBruniaux/ccboard">
  74. <picture>
  75. <source media="(prefers-color-scheme: dark)" srcset="https://starmapper.bruniaux.com/api/map-image/FlorianBruniaux/ccboard?theme=dark" />
  76. <source media="(prefers-color-scheme: light)" srcset="https://starmapper.bruniaux.com/api/map-image/FlorianBruniaux/ccboard?theme=light" />
  77. <img alt="StarMapper — see who stars this repo on a world map" src="https://starmapper.bruniaux.com/api/map-image/FlorianBruniaux/ccboard" />
  78. </picture>
  79. </a>
  80. </p>
  81. ---
  82. ## Installation
  83. ### Recommended: Homebrew (macOS/Linux)
  84. ```bash
  85. brew tap FlorianBruniaux/tap
  86. brew install ccboard
  87. ```
  88. **Why Homebrew?** Simple one-command install, automatic updates via `brew upgrade`, no manual Rust setup required.
  89. ### Alternative: cargo install (requires Rust 1.85+)
  90. ```bash
  91. cargo install ccboard
  92. ```
  93. **Why cargo?** ccboard's target audience (Claude Code users) often has Rust installed. Ensures compatibility and always installs latest crates.io version.
  94. > **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).
  95. ### Alternative: Install Script (macOS/Linux/Windows)
  96. **One-liner install** (no Rust required):
  97. ```bash
  98. 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
  99. ```
  100. This script:
  101. - Auto-detects your OS and architecture
  102. - Downloads the latest pre-compiled binary
  103. - Installs to `~/.local/bin` (customizable with `INSTALL_DIR`)
  104. - Checks if binary is in PATH
  105. **Windows users**: Use Git Bash, WSL, or download manually from releases.
  106. ### Alternative: Pre-built binaries (manual)
  107. Download from [GitHub Releases](https://github.com/FlorianBruniaux/ccboard/releases/latest):
  108. | Platform | Status | Download |
  109. |----------|--------|----------|
  110. | **macOS** (x86_64/ARM64) | ✅ Fully tested | [ccboard-macos-*.tar.gz](https://github.com/FlorianBruniaux/ccboard/releases) |
  111. | **Linux** (x86_64/ARM64) | ⚠️ Community-tested | [ccboard-linux-*.tar.gz](https://github.com/FlorianBruniaux/ccboard/releases) |
  112. | **Windows** (x86_64) | 🧪 Experimental | [ccboard-windows-*.exe.zip](https://github.com/FlorianBruniaux/ccboard/releases) |
  113. **Manual installation** (macOS/Linux):
  114. ```bash
  115. # Extract
  116. tar xzf ccboard-macos-x86_64.tar.gz # or ccboard-linux-*
  117. # Move to PATH
  118. mv ccboard ~/.local/bin/
  119. chmod +x ~/.local/bin/ccboard
  120. ```
  121. **Manual installation** (Windows):
  122. 1. Download `ccboard-windows-x86_64.exe.zip`
  123. 2. Extract `ccboard-windows-x86_64.exe`
  124. 3. Rename to `ccboard.exe`
  125. 4. Move to a directory in your PATH (e.g., `C:\Users\YourName\.local\bin\`)
  126. **Platform support:**
  127. - ✅ **macOS**: Manually tested on every release
  128. - ⚠️ **Linux**: CI-tested, community validation welcome
  129. - 🧪 **Windows**: Best-effort support (feedback appreciated)
  130. ---
  131. ## Quick Start
  132. ```bash
  133. # TUI dashboard (default)
  134. ccboard
  135. # Web interface
  136. ccboard web --port 3333
  137. # Both simultaneously
  138. ccboard both --port 3333
  139. # Stats only (scriptable)
  140. ccboard stats
  141. ```
  142. 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.
  143. ---
  144. ## Screenshots
  145. ### TUI (Terminal)
  146. #### Dashboard - Key Metrics & Model Usage
  147. ![Dashboard](assets/screenshots/tui/tui-01-dashboard.png)
  148. #### Sessions - Project Tree & Search
  149. ![Sessions](assets/screenshots/tui/tui-02-sessions-list.png)
  150. #### Sessions - Detail View
  151. ![Session Detail](assets/screenshots/tui/tui-02-sessions-detail.png)
  152. #### Sessions - Live Process Monitoring
  153. ![Live Sessions](assets/screenshots/tui/tui-02-sessions-live.png)
  154. <details>
  155. <summary>More TUI Screenshots (click to expand)</summary>
  156. #### Configuration - 4-Column Merge View
  157. ![Config](assets/screenshots/tui/tui-03-config.png)
  158. #### Hooks Management
  159. ![Hooks](assets/screenshots/tui/tui-04-hooks.png)
  160. #### Agents, Commands & Skills
  161. ![Agents](assets/screenshots/tui/tui-05-agents.png)
  162. ![Commands](assets/screenshots/tui/tui-05-commands.png)
  163. ![Skills](assets/screenshots/tui/tui-05-skills.png)
  164. #### Cost Analytics
  165. ![Costs Overview](assets/screenshots/tui/tui-06-costs-overview.png)
  166. ![Costs By Model](assets/screenshots/tui/tui-06-costs-by-model.png)
  167. ![Costs Daily](assets/screenshots/tui/tui-06-costs-daily.png)
  168. ![Costs Billing Blocks](assets/screenshots/tui/tui-06-costs-billing-blocks.png)
  169. ![Costs Leaderboard](assets/screenshots/tui/tui-06-costs-leaderboard.png)
  170. ![Costs Top Sessions](assets/screenshots/tui/tui-06-costs-top-sessions.png)
  171. ![Costs Per Project](assets/screenshots/tui/tui-06-costs-per-project.png)
  172. #### History Search
  173. ![History](assets/screenshots/tui/tui-07-history.png)
  174. #### MCP Servers
  175. ![MCP](assets/screenshots/tui/tui-08-mcp.png)
  176. #### Analytics
  177. ![Analytics Overview](assets/screenshots/tui/tui-09-analytics-overview.png)
  178. ![Analytics Trends](assets/screenshots/tui/tui-09-analytics-trends.png)
  179. ![Analytics Patterns](assets/screenshots/tui/tui-09-analytics-patterns.png)
  180. ![Analytics Insights](assets/screenshots/tui/tui-09-analytics-insights.png)
  181. ![Analytics Anomalies](assets/screenshots/tui/tui-09-analytics-anomalies.png)
  182. ![Analytics Summary](assets/screenshots/tui/tui-09-analytics-summary.png)
  183. ![Analytics Costs](assets/screenshots/tui/tui-09-analytics-costs.png)
  184. ![Analytics Discover](assets/screenshots/tui/tui-09-analytics-discover.png)
  185. #### Audit Log
  186. ![Audit Log](assets/screenshots/tui/tui-10-audit-log.png)
  187. #### Plugins
  188. ![Plugins](assets/screenshots/tui/tui-11-plugins.png)
  189. #### Search
  190. ![Search](assets/screenshots/tui/tui-12-search.png)
  191. #### Brain — Cross-session Knowledge Base
  192. ![Brain](assets/screenshots/tui/tui-13-brain.png)
  193. </details>
  194. ---
  195. ### Web Interface
  196. #### Dashboard
  197. ![Web Dashboard](assets/screenshots/web/web-01-dashboard.png)
  198. #### Sessions - Browse & Live Monitoring
  199. ![Web Sessions](assets/screenshots/web/web-02-sessions-list.png)
  200. ![Web Sessions Active](assets/screenshots/web/web-02-sessions-active.png)
  201. <details>
  202. <summary>More Web Screenshots (click to expand)</summary>
  203. #### Configuration
  204. ![Web Config](assets/screenshots/web/web-03-config.png)
  205. ![Web Config Modal](assets/screenshots/web/web-03-config-modal.png)
  206. #### Hooks
  207. ![Web Hooks](assets/screenshots/web/web-04-hooks.png)
  208. #### Agents, Commands & Skills
  209. ![Web Agents](assets/screenshots/web/web-05-agents.png)
  210. ![Web Commands](assets/screenshots/web/web-05-commands.png)
  211. ![Web Skills](assets/screenshots/web/web-05-skills.png)
  212. #### Cost Analytics
  213. ![Web Costs Overview](assets/screenshots/web/web-06-costs-overview.png)
  214. ![Web Costs By Model](assets/screenshots/web/web-06-costs-by-model.png)
  215. ![Web Costs Daily](assets/screenshots/web/web-06-costs-daily.png)
  216. ![Web Costs Billing Blocks](assets/screenshots/web/web-06-costs-billing-blocks.png)
  217. #### History
  218. ![Web History](assets/screenshots/web/web-07-history.png)
  219. #### MCP Servers
  220. ![Web MCP](assets/screenshots/web/web-08-mcp.png)
  221. #### Analytics
  222. ![Web Analytics Overview](assets/screenshots/web/web-09-analytics-overview.png)
  223. ![Web Analytics Trends](assets/screenshots/web/web-09-analytics-trends.png)
  224. ![Web Analytics Patterns](assets/screenshots/web/web-09-analytics-patterns.png)
  225. ![Web Analytics Insights](assets/screenshots/web/web-09-analytics-insights.png)
  226. </details>
  227. ---
  228. ## Why ccboard Exists
  229. **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.
  230. **Solution**: ccboard is the **only tool** dedicated to Claude Code monitoring and management:
  231. - **Zero direct competitors** for Claude Code dashboard (verified 2026-02-04)
  232. - **Not competing with LangSmith/W&B** (they trace LangChain API calls, not local Claude sessions)
  233. - **Fills the gap** between CLI commands and full observability
  234. ### Unique Position
  235. 1. **All-local**: Reads `~/.claude` files, no SaaS/API required
  236. 2. **Unified Dashboard**: 12 tabs (config, hooks, agents, MCP, analytics, security audit, search) vs basic CLI
  237. 3. **Performance**: SQLite cache (89x speedup), handles 10K+ sessions
  238. 4. **Dual Interface**: TUI + Web in single 5.8MB binary
  239. **Risk**: Anthropic could integrate dashboard into Claude Code CLI. But currently, nothing exists.
  240. ---
  241. ## Competitive Landscape
  242. ccboard vs ccusage vs agtrace vs claudelytics — Claude Code monitoring tools compared (verified 2026-02-06):
  243. | Feature | **ccboard** | agtrace | claudelytics | ccusage |
  244. |---------|-------------|---------|--------------|---------|
  245. | **Status** | ✅ Active | ✅ Active | 🔴 Stale 6m | ✅ Active |
  246. | **Stars** | 0 | 23 | 62 | 10,361 |
  247. | **Language** | Rust | Rust | Rust | TypeScript |
  248. | **Type** | TUI+Web | TUI | TUI | CLI |
  249. | | | | | |
  250. | **TUI Dashboard** | ✅ 12 tabs | ✅ Single view | ✅ 8 tabs | ❌ |
  251. | **Config Viewer (3-level merge)** | ✅ | ❌ | ❌ | ❌ |
  252. | **Hooks Viewer + Test** | ✅ | ❌ | ❌ | ❌ |
  253. | **Agents/Commands/Skills Browser** | ✅ | ❌ | ❌ | ❌ |
  254. | **MCP Server Status Detection** | ✅ | ❌ | ❌ | ❌ |
  255. | **SQLite Cache (89x speedup)** | ✅ | ✅ Pointer-based | ❌ | ❌ |
  256. | **Export CSV/JSON** | ✅ | ❌ | ✅ | ✅ JSON |
  257. | **Live File Watcher** | ✅ | ✅ Poll 1s | ❌ | ❌ |
  258. | **Advanced Analytics (Forecast, Budget)** | ✅ 4 views | ❌ | ⚠️ Burn rate | ❌ |
  259. | **Single Binary (no runtime)** | ✅ 5.8MB | ✅ Rust | ✅ Rust | ❌ npm |
  260. | | | | | |
  261. | **MCP Server Mode** | ⏳ Soon | ✅ 6 tools | ❌ | ❌ |
  262. | **Billing Blocks (5h)** | ✅ | ❌ | ✅ | ❌ |
  263. | **Conversation Viewer** | ✅ | ❌ | ✅ | ❌ |
  264. | **Activity Security Audit** | ✅ | ❌ | ❌ | ❌ |
  265. | **Multi-provider** | ❌ | ✅ 3 providers | ❌ | ❌ |
  266. **Unique to ccboard**:
  267. - Only **multi-concern dashboard** (config + hooks + agents + MCP + analytics + security audit)
  268. - Config 3-level merge viewer (global/project/local)
  269. - Hooks syntax highlighting + test mode
  270. - Agents/Commands/Skills browser with invocation stats
  271. - MCP server **status** detection (vs agtrace = MCP server mode)
  272. - SQLite metadata cache (89x faster startup)
  273. - **Advanced Analytics**: 30-day forecasting, budget alerts, session duration stats, usage patterns
  274. - **Activity Security Audit**: credential access detection, destructive command alerts, cross-session violations feed with remediation hints
  275. - **FTS5 Search**: full-text search across all sessions with ranked snippets
  276. - Dual TUI + Web single binary
  277. **References**:
  278. - **agtrace** (23⭐): Observability-focused, MCP self-reflection (6 tools), multi-provider
  279. - **claudelytics** (62⭐, STALE 6m): Feature-rich TUI (8 tabs, billing blocks, conversation viewer)
  280. - **ccusage** (10K⭐): CLI cost tracker (reference for pricing, no dashboard)
  281. **Complementary tools**:
  282. - **[xlaude](https://github.com/Xuanwo/xlaude)** (171 ⭐): Git worktree manager for Claude sessions
  283. - **Complementarity**: xlaude focuses on workspace isolation (PTY sessions, branch management), ccboard on analytics/monitoring
  284. - **Performance comparison**: ccboard lazy loading 15x faster (4.8s vs 72s for 3000 sessions)
  285. - **Use cases**: Use xlaude for session isolation, ccboard for historical analysis and cost tracking
  286. - **Learnings applied**: Environment variables (QW1), message filtering (QW2), performance validation (QW3)
  287. ---
  288. ## Configuration
  289. ### API Usage Estimation
  290. ccboard displays estimated API costs in the Dashboard with plan-based budget tracking. Configure your subscription plan to see accurate percentages and budget limits.
  291. **Add to `~/.claude/settings.json`** (global) **or** `.claude/settings.json` (per-project):
  292. ```json
  293. {
  294. "subscriptionPlan": "max20x"
  295. }
  296. ```
  297. **Available plans:**
  298. | Plan | Subscription Cost | Config Value |
  299. |------|-------------------|--------------|
  300. | Claude Pro | $20/month | `"pro"` |
  301. | Claude Max 5x | $50/month | `"max5x"` |
  302. | Claude Max 20x | $200/month | `"max20x"` |
  303. | API (Pay-as-you-go) | No fixed cost | `"api"` |
  304. **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.
  305. **Dashboard display:**
  306. ```
  307. ┌─ 💰 API Usage (Est.) - Claude Max 20x ─┐
  308. │ Today: $ 2.45 / $200.00 ( 1.2%)│
  309. │ This week: $ 8.12 / $200.00 ( 4.1%)│
  310. │ This month: $78.40 / $200.00 ( 39.2%)│
  311. └──────────────────────────────────────────┘
  312. ```
  313. **Color coding:**
  314. - 🟢 **Green**: < 60% of monthly budget
  315. - 🟡 **Yellow**: 60-80% of monthly budget
  316. - 🔴 **Red**: > 80% of monthly budget
  317. **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.
  318. ### Budget Alerts & Tracking
  319. Configure custom monthly budgets with automatic alerts in the **Analytics tab** (Tab 9 → Overview). Get visual warnings when approaching your spending limit.
  320. **Add to `~/.claude/settings.json`** (global) **or** `.claude/settings.json` (per-project):
  321. ```json
  322. {
  323. "budget": {
  324. "monthlyBudgetUsd": 50.0,
  325. "alertThresholdPct": 80.0
  326. }
  327. }
  328. ```
  329. **Configuration:**
  330. | Field | Type | Description | Default |
  331. |-------|------|-------------|---------|
  332. | `monthlyBudgetUsd` | number | Your monthly spending limit in USD | Required |
  333. | `alertThresholdPct` | number | Alert threshold percentage (0-100) | `80.0` |
  334. **Analytics Overview display:**
  335. ```
  336. ┌─ Budget Status ─────────────────────────────┐
  337. │ Monthly Est: $42.50 │
  338. │ Budget: $50.00 ━━━━━━━━━━━━━━━━ 85% │
  339. │ Remaining: $7.50 (15%) │
  340. │ │
  341. │ ⚠️ WARNING: Approaching budget limit (85%) │
  342. │ 💡 TIP: Projected overage: $5.20 if trend… │
  343. └──────────────────────────────────────────────┘
  344. ```
  345. **Visual indicators:**
  346. - 🟢 **Green bar**: < 60% of budget (safe zone)
  347. - 🟡 **Yellow bar**: 60-80% of budget (caution)
  348. - 🔴 **Red bar + ⚠️**: ≥ 80% of budget (warning)
  349. **Alert types:**
  350. 1. **Budget Warning**: Current cost approaching threshold
  351. 2. **Projected Overage**: Forecast predicts budget exceeded if trend continues
  352. 3. **Usage Spike**: Daily tokens > 2x average (anomaly detection)
  353. **4-level priority** (higher overrides lower):
  354. 1. `~/.claude/settings.json` (global)
  355. 2. `~/.claude/settings.local.json` (global, not committed to git)
  356. 3. `.claude/settings.json` (project, committed)
  357. 4. `.claude/settings.local.json` (project, developer-specific)
  358. **Example workflows:**
  359. - **Solo developer**: Set global budget in `~/.claude/settings.json`
  360. - **Team project**: Set team budget in `.claude/settings.json` (committed), override personally in `.claude/settings.local.json`
  361. - **Multiple projects**: Different budgets per project in each `.claude/settings.json`
  362. ---
  363. ## Usage
  364. ### TUI Mode (Default)
  365. ```bash
  366. ccboard # Launch TUI dashboard
  367. ccboard stats # Print stats and exit
  368. ccboard search "query" # Search sessions
  369. ccboard recent 10 # Show 10 most recent sessions
  370. ```
  371. ### Web Mode
  372. ccboard has **2 web workflows** depending on your use case:
  373. #### Option 1: Production (Single Command) ⭐ Recommended
  374. **For**: Running the full stack (API + Frontend) in production or for general use.
  375. ```bash
  376. ccboard web
  377. ```
  378. **Output**:
  379. ```
  380. ⠋ Loading sessions and statistics...
  381. ✓ Ready in 2.34s (1,247 sessions loaded)
  382. 🌐 Backend API + Frontend: http://127.0.0.1:3333
  383. API endpoints: http://127.0.0.1:3333/api/*
  384. ```
  385. **Features**:
  386. - ✅ Single process, single port
  387. - ✅ WASM frontend embedded in the binary (no separate build step)
  388. - ✅ Real-time data updates via Server-Sent Events (SSE)
  389. - ❌ No hot reload (requires `trunk build` + F5 after code changes when developing)
  390. **When to use**: Daily use, demos, production, or when you just want the web interface running.
  391. ---
  392. #### Option 2: Development (Hot Reload) 🔧
  393. **For**: Developing the frontend with automatic recompilation and browser refresh.
  394. ```bash
  395. # Terminal 1: Start backend API
  396. ccboard web --port 8080
  397. # Terminal 2: Start frontend dev server (run in ccboard repo root)
  398. trunk serve --port 3333
  399. ```
  400. **Output Terminal 1**:
  401. ```
  402. 🌐 Backend API only: http://127.0.0.1:8080/api/*
  403. 💡 Run 'trunk build' to compile frontend
  404. ```
  405. **Output Terminal 2**:
  406. ```
  407. 📦 Starting build...
  408. ✅ Success! App is being served at: http://127.0.0.1:3333
  409. ```
  410. **Features**:
  411. - ✅ Real-time data updates via SSE
  412. - ✅ **Hot reload**: Frontend code changes auto-recompile and refresh browser
  413. - ✅ Separate logs for backend and frontend
  414. - ❌ Two terminals required
  415. **When to use**: When developing the Leptos frontend (editing `crates/ccboard-web/src/**/*.rs`).
  416. **Note**: `trunk serve` automatically proxies `/api/*` requests to `http://localhost:8080` via Trunk.toml config.
  417. ---
  418. ### Dual Mode (TUI + Web)
  419. Run both TUI and web server simultaneously:
  420. ```bash
  421. ccboard both --port 3333
  422. ```
  423. - Web server runs in background
  424. - TUI runs in foreground
  425. - Shared DataStore (same data, live updates)
  426. - Press `q` in TUI to exit both
  427. ### Web Pages
  428. **Available Pages** (100% TUI parity) ✅:
  429. - `/` - Dashboard with KPIs and forecast
  430. - `/sessions` - Sessions browser with **live CPU/RAM monitoring** 🔥
  431. - `/analytics` - Analytics with budget tracking
  432. - `/config` - 4-column configuration viewer
  433. - `/hooks` - Hooks with syntax highlighting
  434. - `/mcp` - MCP servers with status
  435. - `/agents` - Agents/Commands/Skills browser
  436. - `/skills` - Skill invocation leaderboard with `[retired]` badge
  437. - `/costs` - 4 tabs (Overview, By Model, Daily, Billing Blocks)
  438. - `/history` - History search and filters
  439. - `/activity` - Security audit & violations feed
  440. - `/search` - Full-text session search
  441. ### Session Summaries
  442. Generate and cache an AI summary of any session using `claude --print`:
  443. ```bash
  444. # Generate summary (cached to ~/.ccboard/summaries/<id>.md)
  445. ccboard summarize <session-id>
  446. # Regenerate even if cached
  447. ccboard summarize <session-id> --force
  448. # Use a specific model
  449. ccboard summarize <session-id> --model claude-haiku-4-5
  450. ```
  451. 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.
  452. ### Discover — Config Optimization
  453. Analyze your session history to surface recurring patterns and suggest what to extract as **CLAUDE.md rules**, **skills**, or **commands**.
  454. ```bash
  455. # Analyze all projects, last 90 days (default)
  456. ccboard discover --all
  457. # Last 30 days, lower threshold, top 10
  458. ccboard discover --all --since 30d --min-count 2 --top 10
  459. # Current project only
  460. ccboard discover --top 20
  461. # JSON output (pipe to jq)
  462. ccboard discover --all --json | jq '.[0]'
  463. # Semantic analysis via Claude (requires claude in PATH)
  464. ccboard discover --all --llm
  465. ```
  466. **Output example:**
  467. ```
  468. ccboard discover — 1121 sessions · 42 project(s) · since 90d
  469. 📋 CLAUDE.MD RULE
  470. ────────────────────────────────────────────────────────────
  471. write tests before implementation [cross-project]
  472. 234 sessions (28%) · 891 occurrences · score 0.416
  473. → 3a72f1c4-...
  474. 🧩 SKILL
  475. ────────────────────────────────────────────────────────────
  476. security review authentication flow
  477. 71 sessions (8%) · 203 occurrences · score 0.084
  478. ⚡ COMMAND
  479. ────────────────────────────────────────────────────────────
  480. generate prisma migration rollback
  481. 18 sessions (2%) · 44 occurrences · score 0.021
  482. ```
  483. Categories assigned automatically: >20% of sessions → CLAUDE.md rule, ≥5% → skill, else → command. Cross-project patterns get a 1.5× score bonus.
  484. ### Stats Only
  485. ```bash
  486. # Print stats summary and exit
  487. ccboard stats
  488. ```
  489. **Output example:**
  490. ```
  491. ccboard - Claude Code Statistics
  492. ================================
  493. Total Tokens: 12.5M
  494. Input: 8.2M
  495. Output: 3.1M
  496. Cache Read: 890K
  497. Cache Write: 310K
  498. Sessions: 2,340
  499. Messages: 18,450
  500. Cache Hit Ratio: 28.7%
  501. Models:
  502. claude-sonnet-4.5: 9.8M tokens (in: 6.5M, out: 2.3M)
  503. claude-opus-4: 1.2M tokens (in: 800K, out: 400K)
  504. ```
  505. ### Export
  506. Export data to CSV, JSON, or Markdown for external analysis, BI tools, or sharing.
  507. #### Sessions list
  508. ```bash
  509. ccboard export sessions --output sessions.csv # CSV (default)
  510. ccboard export sessions --output sessions.json --format json # JSON
  511. ccboard export sessions --output sessions.md --format md # Markdown table
  512. ccboard export sessions --output recent.csv --since 7d # Last 7 days only
  513. ccboard export sessions --output recent.csv --since 30d # Last 30 days
  514. ```
  515. #### Usage statistics
  516. ```bash
  517. ccboard export stats --output stats.csv # Per-model breakdown CSV
  518. ccboard export stats --output stats.json --format json # Full StatsCache JSON
  519. ccboard export stats --output report.md --format md # Human-readable report
  520. ```
  521. The Markdown report includes: totals (tokens/sessions/messages/cache ratio), per-model table, and last 30 days of daily activity.
  522. #### Billing blocks
  523. ```bash
  524. ccboard export billing --output billing.csv # CSV (default)
  525. ccboard export billing --output billing.json --format json # JSON with full token breakdown
  526. ccboard export billing --output billing.md --format md # Markdown table
  527. ```
  528. #### Single conversation
  529. ```bash
  530. ccboard export conversation <session-id> --output conv.md # Markdown (default)
  531. ccboard export conversation <session-id> --output conv.json --format json
  532. ccboard export conversation <session-id> --output conv.html --format html
  533. ```
  534. ### Report (CI/CD)
  535. 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.
  536. ```bash
  537. # Markdown report, last 7 days (default)
  538. ccboard report
  539. # JSON for machine parsing
  540. ccboard report --format json
  541. # HTML with embedded charts
  542. ccboard report --format html --output report.html
  543. # Last 30 days
  544. ccboard report --since 30d
  545. # Write to file
  546. ccboard report --output weekly-report.md
  547. # Fail CI if token budget exceeded
  548. ccboard report --budget 500000
  549. # Fail CI if error rate > 5%
  550. ccboard report --error-threshold 5
  551. # Combine gates
  552. ccboard report --budget 1000000 --error-threshold 10 --since 30d
  553. ```
  554. **Output example (Markdown):**
  555. ```markdown
  556. # ccboard Report
  557. **Period:** last 7d
  558. **Generated:** 2026-06-24 15:13 UTC
  559. ## Summary
  560. | Metric | Value |
  561. |--------|-------|
  562. | Total Tokens | 14.49B |
  563. | Sessions (period) | 1441 |
  564. | Est. Cost | $54622.19 |
  565. | Error Rate | 0.0% |
  566. | Cache Hit Ratio | 99.9% |
  567. ## Top Tools by Token Usage
  568. | Tool | Calls | Tokens | % of Total | Est. Cost |
  569. |------|-------|--------|------------|-----------|
  570. | Bash | 14050 | 1.46B | 47.6% | $26026.22 |
  571. | Read | 7475 | 677M | 22.1% | $12083.00 |
  572. | Edit | 3825 | 459M | 15.0% | $8205.99 |
  573. ...
  574. ```
  575. **CI gate behavior:**
  576. - `--budget` and `--error-threshold` can be combined
  577. - Exit code 0 when all gates pass, exit code 1 when any gate fails
  578. - Report is always printed to stdout (or `--output` file) regardless of gate result
  579. - Error details go to stderr so stdout remains parseable
  580. ### Skills (invocation leaderboard)
  581. Exact counts of real Skill invocations (the `Skill` tool_use block), never textual mentions of a skill's name in a message.
  582. ```bash
  583. # Full leaderboard, table output
  584. ccboard skills
  585. # JSON for scripting
  586. ccboard skills --json
  587. # Include subagent-driven invocations
  588. ccboard skills --include-subagents
  589. # Filter by time window or project
  590. ccboard skills --since 30d
  591. ccboard skills --project ccboard
  592. # Detail for a single skill
  593. ccboard skills flow-lean
  594. ```
  595. ---
  596. ## Keybindings & Shortcuts
  597. ### Keybindings
  598. #### Global Navigation
  599. | Key | Action |
  600. |-----|--------|
  601. | `q` | Quit application |
  602. | `Tab` / `Shift+Tab` | Navigate tabs forward/backward |
  603. | `1-9` | Jump to specific tab |
  604. | `:` | Open command palette |
  605. | `r` | Refresh data |
  606. | `Esc` | Close popup / Go back |
  607. #### List Navigation
  608. | Key | Action |
  609. |-----|--------|
  610. | `j` / `↓` | Move down |
  611. | `k` / `↑` | Move up |
  612. | `h` / `←` | Move left / Collapse |
  613. | `l` / `→` | Move right / Expand |
  614. | `PgUp` / `PgDn` | Page up/down (10 items) |
  615. | `Enter` | Show detail / Select |
  616. #### File Operations
  617. | Key | Action |
  618. |-----|--------|
  619. | `e` | Edit file in `$EDITOR` |
  620. | `o` | Reveal file in file manager |
  621. #### Tab-Specific
  622. **Sessions**
  623. - `/` - Search sessions
  624. - `Enter` - Show session detail
  625. - `b` - Toggle bookmark on selected session
  626. - `B` - Toggle "bookmarked only" filter
  627. - `s` - Cycle sort mode (date/tokens/duration/messages)
  628. **Config**
  629. - `m` - Show MCP detail modal
  630. - `e` - Edit config file (based on column focus)
  631. **History**
  632. - `/` - Full-text search across sessions
  633. **Costs**
  634. - `Tab` / `←` / `→` - Switch cost views (Overview/By Model/Daily)
  635. **Activity** (Tab/Shift+Tab to reach)
  636. - `r` - Batch-scan all sessions (4 concurrent)
  637. - `Enter` - Analyze selected session individually
  638. - `Tab` - Toggle Sessions ↔ Violations view
  639. - `j/k` - Navigate sessions or violations list
  640. **Search** (Tab/Shift+Tab to reach)
  641. - Type to search — FTS5 full-text search across all sessions
  642. - Results ranked by relevance with highlighted snippets
  643. ### Environment Variables
  644. ccboard supports environment variables for automation and CI/CD workflows:
  645. | Variable | Description | Example |
  646. |----------|-------------|---------|
  647. | `CCBOARD_CLAUDE_HOME` | Override Claude home directory | `CCBOARD_CLAUDE_HOME=/custom/path ccboard stats` |
  648. | `CCBOARD_NON_INTERACTIVE` | Disable interactive prompts (CI/CD mode) | `CCBOARD_NON_INTERACTIVE=1 ccboard stats` |
  649. | `CCBOARD_FORMAT` | Force output format: `json` or `table` | `CCBOARD_FORMAT=json ccboard recent 10` |
  650. | `CCBOARD_NO_COLOR` | Disable ANSI colors (log-friendly) | `CCBOARD_NO_COLOR=1 ccboard search "bug"` |
  651. **Use cases**:
  652. ```bash
  653. # CI/CD: JSON output without colors
  654. CCBOARD_NON_INTERACTIVE=1 CCBOARD_NO_COLOR=1 CCBOARD_FORMAT=json ccboard stats
  655. # Testing: Isolated configuration
  656. CCBOARD_CLAUDE_HOME=/tmp/test-claude ccboard stats
  657. # Automation: Pipe JSON to other tools
  658. CCBOARD_FORMAT=json ccboard sessions search "error" | jq '.[] | .id'
  659. # Log-friendly: No colors for file redirects
  660. CCBOARD_NO_COLOR=1 ccboard recent 50 > sessions.log
  661. ```
  662. ### Command Palette
  663. Press `:` to open the command palette with fuzzy matching:
  664. ```
  665. :dashboard → Jump to Dashboard tab
  666. :sessions → Jump to Sessions tab
  667. :config → Jump to Config tab
  668. :mcp → Jump to MCP tab
  669. :quit → Exit application
  670. ```
  671. ### File Editing
  672. ccboard integrates with your configured editor:
  673. 1. Navigate to any file (agent, session, hook, config)
  674. 2. Press `e` to edit
  675. 3. Editor opens in terminal (terminal state preserved)
  676. 4. Changes detected automatically via file watcher
  677. **Editor priority**: `$VISUAL` > `$EDITOR` > fallback (nano/notepad.exe)
  678. ---
  679. ## Troubleshooting
  680. ### "Stats not loading" or "No sessions found"
  681. Run Claude Code at least once to generate `~/.claude` directory:
  682. ```bash
  683. claude # Or use Claude Code via IDE
  684. ```
  685. Then relaunch ccboard.
  686. ### "WASM compilation failed" (Web mode)
  687. Ensure trunk is installed:
  688. ```bash
  689. cargo install trunk
  690. trunk --version # Should be 0.18+
  691. ```
  692. Then rebuild:
  693. ```bash
  694. cd ccboard-web
  695. trunk build --release
  696. ```
  697. ### "Connection refused" (Web mode)
  698. Check if backend port is in use:
  699. ```bash
  700. lsof -i :8080 # macOS/Linux
  701. netstat -ano | findstr :8080 # Windows
  702. ```
  703. Change port if needed:
  704. ```bash
  705. ccboard web --port 3333
  706. ```
  707. ### Linux: "File manager not opening"
  708. Install xdg-utils:
  709. ```bash
  710. sudo apt install xdg-utils # Debian/Ubuntu
  711. sudo dnf install xdg-utils # Fedora
  712. ```
  713. ### Windows: Terminal rendering issues
  714. Use Windows Terminal (not cmd.exe) for proper Unicode support:
  715. - Download: [Windows Terminal](https://aka.ms/terminal)
  716. - Braille spinners `⠋⠙⠹` render correctly in Windows Terminal
  717. ---
  718. ## Development
  719. ### Stack
  720. ```
  721. ccboard/ # Binary CLI entry point
  722. ├── ccboard-core/ # Data layer (parsers, models, store, watcher)
  723. ├── ccboard-tui/ # Ratatui frontend (12 tabs)
  724. └── ccboard-web/ # Axum API backend + Leptos WASM frontend
  725. ```
  726. **Dependency flow**: `ccboard` → `ccboard-tui` + `ccboard-web` → `ccboard-core`
  727. **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.
  728. For detailed architecture documentation, see [ARCHITECTURE.md](ARCHITECTURE.md).
  729. ### Prerequisites
  730. - Rust 1.85+ (`rustup install stable`)
  731. - Claude Code with `~/.claude` directory
  732. ### Build & Run
  733. ```bash
  734. # Clone repository
  735. git clone https://github.com/FlorianBruniaux/ccboard.git
  736. cd ccboard
  737. # Build all crates
  738. cargo build --all
  739. # Run TUI (default)
  740. cargo run
  741. # Run web interface
  742. cargo run -- web --port 3333
  743. # Run with debug logging
  744. RUST_LOG=ccboard=debug cargo run
  745. ```
  746. ### Testing
  747. ```bash
  748. # Run all tests (383 tests)
  749. cargo test --all
  750. # Run tests for specific crate
  751. cargo test -p ccboard-core
  752. # Run with logging
  753. RUST_LOG=debug cargo test
  754. ```
  755. ### Quality Checks
  756. ```bash
  757. # Format code (REQUIRED before commit)
  758. cargo fmt --all
  759. # Clippy (MUST pass with zero warnings)
  760. cargo clippy --all-targets
  761. # Pre-commit checklist
  762. cargo fmt --all && cargo clippy --all-targets && cargo test --all
  763. ```
  764. ### Watch Mode
  765. ```bash
  766. # Auto-rebuild TUI on changes
  767. cargo watch -x 'run'
  768. # Auto-rebuild web
  769. cargo watch -x 'run -- web'
  770. ```
  771. ### Error Handling Standards
  772. ccboard follows strict Rust error handling practices:
  773. - **anyhow::Result** in binaries (`ccboard`, `ccboard-tui`, `ccboard-web`)
  774. - **thiserror** for custom errors in `ccboard-core`
  775. - **Always** use `.context("description")` with `?` operator
  776. - **No unwrap()** in production code (tests only)
  777. - **Graceful degradation**: Return `Option<T>` + populate `LoadReport`
  778. ### Contributing
  779. Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  780. **Development workflow:**
  781. 1. Fork the repository
  782. 2. Create a feature branch (`git checkout -b feat/amazing-feature`)
  783. 3. Make changes with tests
  784. 4. Run quality checks (`cargo fmt && cargo clippy && cargo test`)
  785. 5. Commit with descriptive message
  786. 6. Push and open a Pull Request
  787. ---
  788. ## Roadmap & Documentation
  789. **Current Status**: 🎉 **PRODUCTION-READY**
  790. ### Completed ✅
  791. - ✅ **Infrastructure**: Stats parser, Settings merge, Session metadata, DataStore, SQLite cache (89x speedup)
  792. - ✅ **TUI Dashboard**: 12 interactive tabs with full keybinding navigation
  793. - ✅ **Web Frontend**: Full Leptos/WASM UI with 100% TUI parity (12 pages)
  794. - ✅ **Live Monitoring**: CPU/RAM/Tokens tracking for active Claude processes via hook injection
  795. - ✅ **Cost Analytics**: 6 views (Overview, By Model, Daily, Usage Periods, Top Sessions, Per Project) + 4-level budget alerts
  796. - ✅ **Advanced Analytics**: 30-day forecasting, hourly heatmap, anomaly detection, usage patterns, actionable insights
  797. - ✅ **Conversation Viewer**: Full JSONL replay with regex search (`/` + `n`/`N`), syntax highlighting, HTML export
  798. - ✅ **Dynamic Pricing**: LiteLLM integration with automatic price updates and local caching
  799. - ✅ **Export Features**: CSV/JSON/Markdown export for sessions, stats, billing, conversations
  800. - ✅ **Activity Security Audit**: Per-session tool audit, credential detection, destructive command alerts, remediation hints
  801. - ✅ **Search Tab**: FTS5 full-text search across all sessions, search-as-you-type, ranked snippets
  802. - ✅ **Discover**: N-gram analysis across session history to suggest CLAUDE.md rules, skills, and commands
  803. - ✅ **Tool Cost Analytics**: Per-tool token tracking, tool chain analysis, cost suggestions engine
  804. - ✅ **Plugin Analytics**: Skill/MCP/agent usage, dead code detection
  805. **Total**: 419 tests passing, 0 clippy warnings
  806. For detailed version history, see [CHANGELOG.md](CHANGELOG.md).
  807. ### Documentation
  808. | Document | Description |
  809. |----------|-------------|
  810. | [User Guide](docs/GUIDE.md) | Complete feature reference: all tabs, keybindings, CLI, tips |
  811. | [ARCHITECTURE.md](ARCHITECTURE.md) | Technical architecture, data flow, concurrency model |
  812. | [CHANGELOG.md](CHANGELOG.md) | Version history with detailed change descriptions |
  813. | [SECURITY.md](SECURITY.md) | Security policy, vulnerability reporting, best practices |
  814. | [CROSS_PLATFORM.md](CROSS_PLATFORM.md) | Platform-specific considerations and validation |
  815. | [CONTRIBUTING.md](CONTRIBUTING.md) | Development guidelines and contribution workflow |
  816. | [API Documentation](docs/API.md) | REST API and SSE endpoints for Web UI |
  817. | [Architecture Decision Records](docs/architecture/) | Key architectural decisions and their rationale |
  818. | [Architecture Decision Records](docs/architecture/) | Key architectural decisions and their rationale |
  819. ---
  820. ## License
  821. Licensed under either of:
  822. - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
  823. - MIT License ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
  824. at your option.
  825. ### Contribution
  826. 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.
  827. ---
  828. ## Acknowledgments
  829. This project was developed following Test-Driven Development (TDD) principles with guidance from Agent Academy.
  830. **Co-Authored-By**: Claude Sonnet 4.5 <noreply@anthropic.com>
  831. ---
  832. ## Author
  833. **Florian Bruniaux** - Independent Developer
  834. 🌐 [florian.bruniaux.com](https://florian.bruniaux.com/) | 💼 [LinkedIn](https://www.linkedin.com/in/florianbruniaux/) | 🐙 [GitHub](https://github.com/FlorianBruniaux)
  835. ---
  836. ## Links
  837. ### Project
  838. - **Repository**: https://github.com/FlorianBruniaux/ccboard
  839. - **Issues**: https://github.com/FlorianBruniaux/ccboard/issues
  840. - **Releases**: https://github.com/FlorianBruniaux/ccboard/releases
  841. - **Crates.io**: https://crates.io/crates/ccboard
  842. - **Documentation**: [User Guide](docs/GUIDE.md) | [CHANGELOG.md](CHANGELOG.md)
  843. <!-- BEGIN GENERATED RELATED PROJECTS -->
  844. <!-- Source: https://github.com/FlorianBruniaux/FlorianBruniaux/blob/main/ecosystem/projects.json; project: ccboard -->
  845. ## Explore the ecosystem
  846. These projects extend the workflow without duplicating this tool:
  847. - **Search with [CC-Sessions](https://github.com/FlorianBruniaux/cc-sessions)**: move from the dashboard to a focused CLI search of local history.
  848. - **Measure with [cc-skill-usage](https://github.com/FlorianBruniaux/cc-skill-usage)**: add a specialist analysis of real skill invocations.
  849. - **Learn with [Claude Code Ultimate Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)**: connect observed signals to the guide's observability practices.
  850. - **Route with [CC-Copilot Bridge](https://github.com/FlorianBruniaux/cc-copilot-bridge)**: observe sessions whose model provider can be selected through the bridge.
  851. [Browse the complete open-source galaxy](https://github.com/FlorianBruniaux#open-source-galaxy)
  852. <!-- END GENERATED RELATED PROJECTS -->
  853. ---
  854. **Made with ❤️ for the Claude Code community**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.