claude-dashboard

module
v0.17.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 20, 2026 License: MIT

README ΒΆ

claude-dashboard

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

GitHub Stars CI Go Latest Release tmux


Demo

claude-dashboard 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-dashboard block to ~/.tmux.conf: F12 mouse toggle, Ctrl+S history 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 .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
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 claude in 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 .jsonl files 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 o to 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.

Star History

Star History Chart

License

MIT

Directories ΒΆ

Path Synopsis
cmd
internal
app
ui

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL