README
ΒΆ
claude-dashboard
k9s-style TUI for managing Claude Code sessions with real-time monitoring, conversation history, and process-based session detection.
Demo

Recorded with VHS from demo/demo.tape. The sessions in the recording run a stub in place of claude.
Quick Start
Homebrew
brew install seunggabi/tap/claude-dashboard
Install script
curl -fsSL https://raw.githubusercontent.com/seunggabi/claude-dashboard/main/install.sh | bash
This installs the binary to ~/.local/bin. To install it under a different name:
curl -fsSL https://raw.githubusercontent.com/seunggabi/claude-dashboard/main/install.sh | bash -s -- --name <your-binary-name>
Go
go install github.com/seunggabi/claude-dashboard/cmd/claude-dashboard@latest
From source
git clone https://github.com/seunggabi/claude-dashboard.git
cd claude-dashboard
make install
First run
claude-dashboard # Launch the TUI dashboard
The first run performs a one-time setup. You can repeat it at any time with claude-dashboard setup. Setup:
- installs three helper scripts to
~/.local/bin/ - appends a
claude-dashboardblock to~/.tmux.conf:F12mouse toggle,Ctrl+Shistory save, a status bar with waiting/active session counts and version info, mouse mode on, and a 50,000-line scrollback
π‘ Pro Tip: Super Fast Session Creation
Type just cdn instead of claude-dashboard new:
# One-line setup (adds the alias to your shell rc file)
source <(curl -fsSL https://raw.githubusercontent.com/seunggabi/claude-dashboard/main/alias.sh)
# Before: claude-dashboard new my-project --path ~/code/foo
# After: cdn my-project --path ~/code/foo β‘οΈ
cdn -r # Resume (interactive picker)
cdn -c # Continue most recent conversation
cdn my-project -r # Resume with session name
π Upgrade
# Homebrew
brew update
brew upgrade claude-dashboard
# Install script
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 again to apply new tmux configuration:
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
.jsonllogs. - 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 installand you're done
Sessions run inside tmux - close your terminal, shut your laptop, and come back anytime. k9s-style vim navigation with real-time CPU/memory monitoring.
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 |
d |
Session detail view |
o |
Overview: title, last prompt and todos |
/ |
Filter / search sessions |
r |
Manual refresh |
? |
Help overlay |
esc |
Go back / cancel |
q |
Quit |
Detail View
| Key | Action |
|---|---|
l |
View session logs |
K |
Kill session (with confirmation) |
esc |
Back to dashboard |
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 |
Inside an Attached Session
These are tmux bindings added by claude-dashboard setup, plus the tmux defaults they build on.
| Key | Action |
|---|---|
Ctrl+B d |
Detach and return to the dashboard |
Ctrl+B g |
Open the dashboard in a popup; enter switches to the selected session, q closes it (tmux 3.2+) |
Ctrl+S |
Save the entire pane history to a file in ~/Desktop/ |
F12 |
Toggle mouse mode (ON: scroll with mouse, OFF: easy text select) |
Ctrl+B [ |
Scroll history in copy mode, q to exit |
To copy text while mouse mode is on, hold Option (β₯) (macOS) or Shift (Linux) while dragging.
Features
- Session Dashboard - All Claude sessions in one table with real-time status, CPU/memory, and uptime (auto-refreshes every 2s).
- Session Detection - Lists tmux sessions created by claude-dashboard, any other tmux session with
claudein its process tree, and Claude processes running in plain terminal tabs. - Log Viewer (
l) - For tmux sessions, the pane scrollback. For terminal sessions, the conversation history from the.jsonlfiles in~/.claude/projects/. - Attach / Detach (
enter/Ctrl+B d) - Attach to tmux sessions and return to the dashboard on detach. Terminal sessions are read-only: they can be viewed but not attached or killed. - Overview - Press
oto see every session at once: its title, the last prompt you typed, and its unfinished todos. Read from the Claude Code conversation log, so nothing has to be configured. - Session Colors - Each session gets a color derived from its name, shown as a marker at the start of its row. When you attach from claude-dashboard, the session name in the tmux status bar (
status-left) uses the same color. The option is set on that session only. - Git Branch - The BRANCH column shows the branch checked out in each session's directory, so clones of the same repository are easy to tell apart. The filter matches it too.
Create Session
TUI: Press n to create interactively. CLI:
claude-dashboard new # Auto-name from current directory
claude-dashboard new my-project # Explicit name
claude-dashboard new --path ~/project # Specify directory
claude-dashboard new --args "--model opus"
Session names may contain letters, digits, _ and -. A name derived from a directory has every other character replaced with -, so ~/code/my.app becomes code-my-app.
If a session with the same name already exists, new attaches to it instead.
Claude CLI Pass-through Options
Flags other than --path and --args are forwarded to claude:
| Flag | Description |
|---|---|
-r, --resume |
Resume a conversation by session ID, or open interactive picker |
-c, --continue |
Continue the most recent conversation in the current directory |
--model <model> |
Specify model (e.g., opus, sonnet) |
claude-dashboard new my-project -c
claude-dashboard new my-project --path ~/code/foo -r
Status Detection
| Status | Indicator | Detected when |
|---|---|---|
β active |
Green | The tmux session produced output in the last 2 seconds |
β waiting |
Amber | One of the last 20 pane lines ends with ? or contains a y/n prompt |
β idle |
Gray | Neither of the above |
β terminal |
Blue | Claude is running in a terminal tab outside tmux (read-only) |
Exact status with Claude Code hooks (optional)
The checks above are a guess from the screen. Claude Code hooks can report the state instead: a session shows waiting as soon as Claude asks for permission or asks a question, and active while Claude works, even when its output is quiet. Add this to ~/.claude/settings.json (merge it into an existing hooks key):
{
"hooks": {
"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "claude-dashboard hook active" }] }],
"PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "claude-dashboard hook active" }] }],
"PermissionRequest": [{ "matcher": "*", "hooks": [{ "type": "command", "command": "claude-dashboard hook waiting" }] }],
"Notification": [{ "matcher": "elicitation_dialog", "hooks": [{ "type": "command", "command": "claude-dashboard hook waiting" }] }],
"Stop": [{ "hooks": [{ "type": "command", "command": "claude-dashboard hook idle" }] }],
"SessionEnd": [{ "hooks": [{ "type": "command", "command": "claude-dashboard hook idle" }] }]
}
}
claude-dashboard hook stores the state in the @claude_state option of the tmux session that runs Claude, and does nothing outside tmux. After idle (Claude finished its turn) the screen check above decides between waiting and idle. Claude Code fires no hook when you interrupt it or cancel a prompt, so the screen check also takes over when an active report sees no output for 30 seconds, or when the pane keeps changing more than 5 seconds after a waiting report. The state belongs to the tmux session, so two Claude panes in one session share it.
Configuration
~/.claude-dashboard/config.yaml (optional; these are the defaults):
refresh_interval: 2s # Auto-refresh interval
session_prefix: "cd-" # Prefix for sessions created by claude-dashboard
default_dir: "" # Directory pre-filled in the new session form (default: current directory)
log_history: 1000 # Number of pane lines shown in the log viewer
Usage
claude-dashboard # Launch TUI dashboard
claude-dashboard new [name] # Create session (auto-name if omitted)
claude-dashboard attach <session> # Attach directly (skip TUI)
claude-dashboard status # Waiting/active counts, used by the tmux status bar
claude-dashboard setup # Install helper scripts & configure tmux
claude-dashboard --version # Show version
claude-dashboard --help # Show help
Requirements
- tmux (session backend)
- macOS or Linux
- Go 1.24+ (only for building from source)
# macOS
brew install tmux
# Ubuntu/Debian
sudo apt install tmux
Development
make build # Build to bin/claude-dashboard
make test # Run tests
make demo # Re-record demo/demo.gif (requires vhs and tmux)
Project Structure
claude-dashboard/
βββ cmd/claude-dashboard/main.go # CLI entry point and argument parsing
βββ internal/
β βββ app/app.go # Bubble Tea model: Update, View, key handling
β βββ session/ # Session management
β β βββ session.go # Session data model
β β βββ detector.go # Discover sessions from tmux and the process table
β β βββ manager.go # Create, kill, logs, filter
β βββ tmux/ # tmux integration
β β βββ client.go # Command wrapper
β β βββ parser.go # Output parser
β βββ conversation/reader.go # Parse .jsonl files from ~/.claude/projects/
β βββ monitor/ # Resource monitoring
β β βββ process.go # Process table via ps, CPU/memory aggregation
β β βββ ticker.go # Periodic refresh
β βββ setup/ # `setup` command
β β βββ setup.go # Installs helper scripts, edits ~/.tmux.conf
β β βββ scripts/ # Helper scripts embedded in the binary
β βββ 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
β βββ config/config.go # YAML configuration
β βββ styles/styles.go # Lipgloss styles
βββ demo/ # VHS tape and stub for recording the demo
βββ install.sh # Install script
βββ alias.sh # Adds the cdn alias
βββ Makefile # build, install, test, demo
βββ .goreleaser.yml # Release automation
Tech Stack
- Bubble Tea - Elm architecture TUI framework
- Bubbles - TUI components (viewport, textinput)
- Lipgloss - Style definitions
- tmux - Terminal multiplexer for session persistence
Contributing
Contributions are welcome! Please open an issue or submit a pull request.