CcboardCAUTION

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

# Using Claude Code command
/ccboard-install

# Or manually via cargo
cargo install ccboard

# Launch TUI
/dashboard

# Or run directly
ccboard

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: ccboard
description: "Launch and navigate the ccboard TUI/Web dashboard for Claude Code. Use when monitoring token usage, tracking costs, browsing sessions, or checking MCP server status across projects."
allowed-tools: Bash(ccboard*)
effort: low
metadata:
  version: 0.1.0
---

# ccboard - Claude Code dashboard

Comprehensive TUI/Web dashboard for monitoring and managing your Claude Code usage.

## Overview

ccboard provides a unified interface to visualize and explore all your Claude Code data:

- **Sessions**: Browse all conversations across your projects
- **Statistics**: Real-time token usage, cache hit rates, activity trends
- **MCP Servers**: Monitor and manage Model Context Protocol servers
- **Costs**: Track spending with detailed token breakdown and pricing
- **Configuration**: View cascading settings (Global > Project > Local)
- **Hooks**: Explore pre/post execution hooks and automation
- **Agents**: Manage custom agents, commands, and skills
- **History**: Search across all messages with full-text search

## Installation

### Via cargo (recommended)

```bash
# Using Claude Code command
/ccboard-install

# Or manually
cargo install ccboard
```

### Requirements

- Rust 1.70+ and Cargo
- Claude Code installed (reads from `~/.claude/`)

## Commands

| Command | Description | Shortcut |
|---------|-------------|----------|
| `/dashboard` | Launch TUI dashboard | `ccboard` |
| `/mcp-status` | Open MCP servers tab | Press `8` |
| `/costs` | Open costs analysis | Press `6` |
| `/sessions` | Browse sessions | Press `2` |
| `/ccboard-web` | Launch web UI | `ccboard web` |
| `/ccboard-install` | Install/update ccboard | - |

## Features

### 8 interactive tabs

#### 1. Dashboard (press `1`)
- Token usage statistics
- Session count
- Messages sent
- Cache hit ratio
- MCP server count
- 7-day activity sparkline
- Top 5 models usage gauges

#### 2. Sessions (press `2`)
- Dual-pane: Project tree + Session list
- Metadata: timestamps, duration, tokens, models
- Search: Filter by project, message, or model (press `/`)
- File operations: `e` to edit JSONL, `o` to reveal in finder

#### 3. Config (press `3`)
- 4-column cascading view: Global | Project | Local | Merged
- Settings inheritance visualization
- MCP servers configuration
- Rules (CLAUDE.md) preview
- Permissions, hooks, environment variables
- Edit config with `e` key

#### 4. Hooks (press `4`)
- Event-based hook browsing (PreToolUse, UserPromptSubmit)
- Hook bash script preview
- Match patterns and conditions
- File path tracking for easy editing

#### 5. Agents (press `5`)
- 3 sub-tabs: Agents (12) | / Commands (5) | ★ Skills (0)
- Frontmatter metadata extraction
- File preview and editing
- Recursive directory scanning

#### 6. Costs (press `6`)
- 3 views: Overview | By Model | Daily Trend
- Token breakdown: input, output, cache read/write
- Pricing: total estimated costs
- Model distribution breakdown

#### 7. History (press `7`)
- Full-text search across all sessions
- Activity by hour histogram (24h)
- 7-day sparkline
- All messages searchable

#### 8. MCP (press `8`) **NEW**
- Dual-pane: Server list (35%) | Details (65%)
- Live status detection: ● Running, ○ Stopped, ? Unknown
- Full server details: command, args, environment vars
- Quick actions: `e` edit config, `o` reveal file, `r` refresh status

### Navigation

**Global Keys**:
- `1-8` : Jump to tab
- `Tab` / `Shift+Tab` : Navigate tabs
- `q` : Quit
- `F5` : Refresh data

**Vim-style**:
- `h/j/k/l` : Navigate (left/down/up/right)
- `←/→/↑/↓` : Arrow alternatives

**Common Actions**:
- `Enter` : View details / Focus pane
- `e` : Edit file in $EDITOR
- `o` : Reveal file in finder
- `/` : Search (in Sessions/History tabs)
- `Esc` : Close popup / Cancel

### Real-time Monitoring

ccboard includes a file watcher that monitors `~/.claude/` for changes:

- **Stats updates**: Live refresh when `stats-cache.json` changes
- **Session updates**: New sessions appear automatically
- **Config updates**: Settings changes reflected in UI
- **500ms debounce**: Prevents excessive updates

### File editing

Press `e` on any item to open in your preferred editor:

- Uses `$VISUAL` > `$EDITOR` > platform default (nano/notepad)
- Supports: Sessions (JSONL), Config (JSON), Hooks (Shell), Agents (Markdown)
- Terminal state preserved (alternate screen mode)
- Cross-platform (macOS, Linux, Windows)

### MCP server management

The MCP tab provides comprehensive server monitoring:

**Status Detection** (Unix):
- Checks running processes via `ps aux`
- Extracts package name from command
- Displays PID when running
- Windows shows "Unknown" status

**Server Details**:
- Full command and arguments
- Environment variables with values
- Config file path (`~/.claude/claude_desktop_config.json`)
- Quick edit/reveal actions

**Navigation**:
- `h/l` or `←/→` : Switch between list and details
- `j/k` or `↑/↓` : Select server
- `Enter` : Focus detail pane
- `e` : Edit MCP config
- `o` : Reveal config in finder
- `r` : Refresh server status

## Usage examples

### Daily monitoring

```bash
# Launch dashboard
/dashboard

# Check activity and costs
# Press '1' for overview
# Press '6' for costs breakdown
# Press '7' for recent history
```

### MCP troubleshooting

```bash
# Open MCP tab
/mcp-status

# Or: ccboard then press '8'

# Check server status (● green = running)
# Press 'e' to edit config if needed
# Press 'r' to refresh status after changes
```

### Session analysis

```bash
# Browse sessions
/sessions

# Press '/' to search
# Filter by project: /my-project
# Filter by model: /opus
# Press 'e' on session to view full JSONL
```

### Cost tracking

```bash
# View costs
/costs

# Press '1' for overview
# Press '2' for breakdown by model
# Press '3' for daily trend

# Identify expensive sessions
# Track cache efficiency (99.9% hit rate)
```

## Web interface

Launch browser-based interface for remote monitoring:

```bash
# Launch web UI
/ccboard-web

# Or with custom port
ccboard web --port 8080

#

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

declared (1 observation(s))

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (4)

whitepapers/recap-cards/en/_extensions

whitepapers/recap-cards/fr/_extensions

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Gates applied: no_behavioural_pass.