Skip to content

README.md

Latest commit

 

History

History
313 lines (232 loc) · 11.2 KB

README.md

File metadata and controls

313 lines (232 loc) · 11.2 KB
Raw

claude-dashboard

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

License: MIT GitHub Stars Go Latest Release tmux

Demo

claude-dashboard 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  ⚡️

# Resume or continue conversations instantly
cdn -r                                 # Resume (interactive picker)
cdn -c                                 # Continue most recent conversation
cdn my-project -r                      # Resume with session name

🔄 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

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
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 - All Claude sessions in one table with real-time status, CPU/memory, and uptime (auto-refreshes every 2s). Detects managed sessions, tmux sessions, process tree, and terminal tabs.
  • Conversation Log Viewer (l) - Browse conversation history from ~/.claude/projects/ .jsonl files. Read-only, no attachment needed.
  • Attach / Detach (enter / Ctrl+B d) - Attach to tmux sessions; terminal sessions are read-only.

Tips

Action How
Copy text (macOS) Hold Option (⌥) + drag, then Cmd+C
Copy text (Linux) Hold Shift + drag, then Ctrl+Shift+C
Scroll history Ctrl+B [ to enter copy mode, q to exit
Toggle mouse F12 (ON: scroll with mouse, OFF: easy text select)
Save pane history Ctrl+S in attached session (saves to ~/Desktop/)

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"

Claude CLI Pass-through Options

Flags not recognized by claude-dashboard (--path, --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

If a session with the same name already exists, it automatically attaches instead.

Status Detection

Status Indicator Description
● active Green Output is streaming
○ idle Gray Prompt visible, no activity
◎ waiting Amber Input prompt or Y/n question
⊘ terminal Blue Claude in terminal tab (read-only)

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

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 setup                 # Install helper scripts & configure tmux
claude-dashboard --version             # Show version
claude-dashboard --help                # Show 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

Star History Chart

License

MIT