claude-dashboard

k9s-style TUI for managing Claude Code sessions with real-time monitoring, conversation history, and process-based session detection.

Demo

Quick Start

Homebrew

brew install seunggabi/tap/claude-dashboard
# Setup is automatic on first run, or run manually:
claude-dashboard setup

Manual Installation

curl -fsSL https://raw.githubusercontent.com/seunggabi/claude-dashboard/main/install.sh | bash
# Setup is automatic on first run, or run manually:
claude-dashboard setup

Setup includes:

✅ Installs helper scripts to ~/.local/bin/
✅ Configures ~/.tmux.conf for F12 mouse toggle and Ctrl+S history save
✅ Adds status bar with version info
✅ Enables mouse mode by default

This deploys the binary to ~/.local/bin. For a custom binary name:

~/.local/bin/claude-dashboard

curl -fsSL https://raw.githubusercontent.com/seunggabi/claude-dashboard/main/install.sh | bash -s -- --name <your-binary-name>

Install via Go

go install github.com/seunggabi/claude-dashboard/cmd/claude-dashboard@latest

Build from Source

git clone https://github.com/seunggabi/claude-dashboard.git
cd claude-dashboard
make install

First run:

claude-dashboard   # Launch the TUI dashboard

💡 Pro Tip: Super Fast Session Creation

Type just cdn instead of claude-dashboard new - save time with every session!

# One-line setup (add to your ~/.zshrc or ~/.bashrc for permanent use)
source <(curl -fsSL https://raw.githubusercontent.com/seunggabi/claude-dashboard/main/alias.sh)

Example:

# Before: claude-dashboard new my-project --path ~/code/foo
# After:  cdn my-project --path ~/code/foo  ⚡️

🔄 Upgrade

Keep claude-dashboard up to date with the latest features:

# Homebrew
brew update
brew upgrade claude-dashboard

# Manual installation
curl -fsSL https://raw.githubusercontent.com/seunggabi/claude-dashboard/main/install.sh | bash

# Go
go install github.com/seunggabi/claude-dashboard/cmd/claude-dashboard@latest

After upgrading, run setup to apply new configurations:

claude-dashboard setup

Why claude-dashboard

The Problem

Running multiple Claude Code sessions across different projects quickly becomes unmanageable:

Lost sessions - Terminal closed? Session gone. What was Claude doing?
No overview - Which session is active? How long has it been running? What are resource usage patterns?
Context switching - Constantly hunting through terminal tabs, tmux windows, and scattered .jsonl logs.
Session discovery - Sessions hidden in tmux, terminal tabs, or started by other tools.

The Solution

claude-dashboard gives you a single pane of glass for all your Claude Code sessions:

Unified session detection - Finds Claude sessions in tmux, terminal tabs, and anywhere in the process tree
Conversation history - View Claude's past interactions directly from the dashboard
Real-time monitoring - CPU, memory, status, and uptime at a glance
Session persistence - Sessions keep running in tmux; detach anytime and come back
Single binary - One brew install and you're done

Session Persistence

Every Claude Code session runs inside tmux. Close your terminal, shut your laptop - sessions keep running. Come back anytime and re-attach exactly where you left off.

Real-time Monitoring

Column	Description
Name	Session identifier
Project	Project directory name
Status	`● active` / `○ idle` / `◎ waiting` / `⊘ terminal`
Uptime	Time since session creation
CPU	CPU usage (process tree)
Memory	Memory usage (process tree)
Path	Working directory

k9s-style Keybindings

If you've used k9s, you'll feel right at home. Vim-style navigation, single-key actions, instant feedback.

Keybindings

Dashboard

Key	Action
`↑` / `k`	Move cursor up
`↓` / `j`	Move cursor down
`enter`	Attach to session
`n`	Create new session
`K`	Kill session (with confirmation)
`Ctrl+K`	Kill all idle sessions (with confirmation)
`l`	View session logs
`Ctrl+S`	Save entire pane history to file (in attached session)
`d`	Session detail view
`/`	Filter / search sessions
`r`	Manual refresh
`?`	Help overlay
`esc`	Go back / cancel
`q`	Quit

Logs Viewer

Key	Action
`↑` / `k`	Scroll up
`↓` / `j`	Scroll down
`PgUp` / `PgDn`	Page up / down (macOS: `Fn+↑` / `Fn+↓`)
`esc`	Back to dashboard
`q`	Quit

Features

Session Dashboard

View all Claude Code sessions in a table with real-time status, resource usage, and uptime. Auto-refreshes every 2 seconds. Includes sessions from:

Managed cd-* prefix sessions
Existing tmux sessions with "claude" in the name
Claude processes detected anywhere in the process tree via BFS scan
Claude running in terminal tabs (read-only, shown as ⊘ terminal)

Conversation Log Viewer

Press l to view Claude's conversation history from captured .jsonl files in ~/.claude/projects/. Features:

Scrollable viewport for reading past interactions
Works for both tmux and terminal sessions
Automatically parses conversation structure
No attachment needed - read-only access to conversation state

Attach / Detach

Press enter to attach to any session (tmux sessions only; terminal sessions are read-only). Use Ctrl+B d (tmux detach) to return to the dashboard. Sessions continue running in the background.

Tips

Copy/Paste in Attached Sessions

Mouse mode is enabled by default for smooth scrolling. To copy text:

macOS: Hold Option (⌥) key while dragging to select text, then Cmd+C to copy
Linux: Hold Shift key while dragging to select text, then Ctrl+Shift+C to copy

Scrolling through history:

Press Ctrl+B [ to enter copy mode
Use arrow keys, PgUp/PgDn (macOS: Fn+↑/Fn+↓), or vi keys (j/k) to scroll
Press q or Esc to exit copy mode

Copy text while Claude is actively outputting:

Press Ctrl+B [ to freeze the screen in copy mode, then select and copy text

Toggle Mouse Mode:

Press F12 to toggle mouse mode on/off (super easy!)
Toggle displays message: Mouse: ON or Mouse: OFF
ON (default): Mouse wheel scrolling enabled, use Option/Shift + drag to copy text
OFF: Easy text selection by dragging (no modifier key needed), scroll with Ctrl+B [

Save Pane History:

Press Ctrl+S (inside an attached tmux session) to save the entire scrollback history to a file
Files are saved to ~/Desktop/ (or ~/ if Desktop doesn't exist) with timestamp: tmux-history_<session-name>_<timestamp>.txt
Captures everything from the beginning of the pane's history, not just what's visible on screen
Perfect for preserving long Claude conversations or debugging sessions

Setup:
Setup is automatic on first run, or you can run it manually:

claude-dashboard setup

This will:

Install helper scripts (claude-dashboard-mouse-toggle, claude-dashboard-status-bar, claude-dashboard-save-history) to ~/.local/bin/
Add F12 key binding (mouse toggle) and Ctrl+S key binding (save history) to ~/.tmux.conf
Configure status bar with version check and mouse status
Enable mouse mode by default
Reload tmux configuration if tmux is running

Create Session (TUI)

Press n to create a new session interactively. Enter a name and project directory - claude-dashboard creates a tmux session running claude in that directory.

Create Session (CLI)

Use the new command from your shell:

# Auto-generate name from current directory (~/project/foo → cd-project-foo)
claude-dashboard new

# Explicit session name
claude-dashboard new my-project

# Specify working directory
claude-dashboard new --path ~/my/project

# Pass arguments to claude
claude-dashboard new --args "--model opus"

If a session with the same name already exists, it automatically attaches to it instead of creating a new one.

Combine options freely: claude-dashboard new my-project --path ~/code/foo --args "--model sonnet"

Kill Session

Press K to terminate a single session. Press Ctrl+K to kill all idle sessions at once. Both actions always show a confirmation prompt before killing (safety first).

Filter / Search

Press / to filter sessions by name, project, status, or path. Press esc to clear the filter.

Session Detail

Press d for a detailed view showing PID, CPU, memory, path, start time, attached status, and session type.

Session Naming

Type	Pattern	Example	Detection Method
Managed sessions	`cd-<name>` prefix	`cd-my-project`	Dashboard creates these
Named tmux sessions	Contains "claude"	`claude-api-work`	tmux session list
Process-based detection	No naming requirement	Any Claude process	BFS process tree scan
Terminal sessions	No naming requirement	Claude in terminal tab	Terminal process detection

Session creation:

TUI: Press n in the dashboard to create a new cd-* prefixed session
CLI: Use claude-dashboard new [name] to create from the command line
Existing: Any tmux session with "claude" in the name is detected automatically
Process-based: Claude running anywhere in the process tree is found via BFS scan
Terminal: Claude running in a regular terminal tab is detected (read-only, shown as ⊘ terminal)

Status Detection

Status varies by session type:

tmux Sessions

Status determined by analyzing tmux pane content:

Status	Indicator	Detection
`● active`	Green	Output is streaming
`○ idle`	Gray	Prompt visible, no activity
`◎ waiting`	Amber	Input prompt or Y/n question
`? unknown`	-	Unable to determine

Terminal Sessions

Terminal sessions (outside tmux) are shown with status:

Status	Indicator	Detection
`⊘ terminal`	Blue	Claude process detected in terminal

Terminal sessions are read-only: you can view conversation history via l but cannot attach. Use tmux sessions for interactive work.

Configuration

~/.claude-dashboard/config.yaml:

refresh_interval: 2s       # Auto-refresh interval
session_prefix: "cd-"      # Prefix for managed sessions
default_dir: ""            # Default project directory for new sessions
log_history: 1000          # Number of log lines to capture

Requirements

tmux (session backend)
Go 1.25+ (only for building from source)

Install tmux

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

Usage

TUI Dashboard

# Launch the interactive TUI dashboard
claude-dashboard

Create Sessions from CLI

# Create with auto-generated name from current path (~/project/foo → cd-project-foo)
claude-dashboard new

# Create with explicit name
claude-dashboard new my-project

# Create in a specific directory
claude-dashboard new my-project --path ~/code/foo

# Pass arguments to claude (e.g., --model opus)
claude-dashboard new my-project --args "--model opus"

# Combine options
claude-dashboard new my-project --path ~/code/foo --args "--model sonnet"

Attach to Sessions

# Attach to a session directly (skip TUI)
claude-dashboard attach cd-my-project

General

# Run setup (installs helper scripts and configures tmux)
claude-dashboard setup

# Show version
claude-dashboard --version

# Show help
claude-dashboard --help

Project Structure

claude-dashboard/
├── cmd/claude-dashboard/main.go      # CLI entry point
├── internal/
│   ├── app/                          # Bubble Tea application
│   │   ├── app.go                    # Main model, Update, View
│   │   └── keys.go                   # Keybinding definitions
│   ├── session/                      # Session management
│   │   ├── session.go                # Session data model
│   │   ├── detector.go               # Discover sessions from tmux/terminal/processes
│   │   └── manager.go                # CRUD operations
│   ├── tmux/                         # tmux integration
│   │   ├── client.go                 # Command wrapper
│   │   └── parser.go                 # Output parser
│   ├── conversation/                 # Conversation history
│   │   └── reader.go                 # Parse .jsonl files from ~/.claude/projects/
│   ├── ui/                           # View components
│   │   ├── dashboard.go              # Session table
│   │   ├── logs.go                   # Log viewer (viewport)
│   │   ├── detail.go                 # Detail view
│   │   ├── create.go                 # New session form
│   │   ├── help.go                   # Help overlay
│   │   └── statusbar.go             # Status bar
│   ├── monitor/                      # Resource monitoring
│   │   ├── process.go                # CPU/memory via ps, process tree BFS
│   │   └── ticker.go                 # Periodic refresh
│   ├── config/config.go              # YAML configuration
│   └── styles/styles.go              # Lipgloss styles
├── LICENSE                           # MIT
├── Makefile                          # build, install, clean
└── .goreleaser.yml                   # Release automation

Tech Stack

Bubble Tea - Elm architecture TUI framework
Bubbles - TUI components (table, viewport, textinput)
Lipgloss - Style definitions
tmux - Terminal multiplexer for session persistence

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Star History

License

MIT

seunggabi/claude-dashboard