🖥️ Claw Dashboard

A beautiful, real-time terminal dashboard for monitoring OpenClaw instances — inspired by modern system monitors like btop, htop, and mactop.

Coverage Report: Run npm run test:coverage to generate detailed coverage reports in coverage/.

✨ Features

• 🎨 Stunning Visuals: ASCII art logo, gradient colors, donut charts, and progress bars
• 📊 Real-time Monitoring: Auto-refreshes every 2 seconds
• 🖥️ System Stats: CPU usage (per-core + average), Memory usage with visual gauges
• 🎮 GPU Monitoring: Apple Silicon GPU support (temperature, VRAM utilization)
• 📈 Top Processes: Live view of top CPU and memory consuming processes
• 🤖 OpenClaw Integration: Live session tracking, agent status, security audit
• 📱 Session Management: View all active sessions with token usage
• ⚡ Lightweight: Built with Node.js and blessed for minimal resource usage
• 🔄 Auto-save: Dashboard state persists across restarts
• 📤 Export Scheduling: Automated metric exports with cron-like scheduling
• 🎛️ Widget Arrangement: Drag-and-drop widget reordering with w key
• 📌 Widget Pinning: Pin favorite widgets to top row with Alt+1-9
• 📸 Snapshots: Export/import dashboard configurations
• 🎨 Theme Selector: Interactive theme picker with auto-detection
• 🖱️ Command Palette: Quick access to all commands with Ctrl+K

🚀 Quick Start

Prerequisites

• Node.js v18+
• OpenClaw installed and configured
• macOS (Apple Silicon optimized)

Installation

# Install globally (recommended)
npm install -g claw-dashboard

# Or run without installing
npx claw-dashboard

Usage

# Run the dashboard
clawdash

# Or with npm start (if installed locally)
npm start

# Run with plugin hot-reload (development)
clawdash --watch

🎮 Controls

Basic Controls

| Key | Action | |-----|--------| | q or Q | Quit the dashboard | | r or R | Force refresh data | | p | Toggle performance metrics overlay | | P or Space | Pause/resume auto-refresh | | o | Cycle session sort (time/tokens/idle/name) | | ? or h | Toggle help panel | | s or S | Open/close settings panel | | Esc | Close current modal | | Ctrl+C | Quit gracefully | | Ctrl+K | Open command palette | | v | Show version info |

Widget Controls

| Key | Action | |-----|--------| | 1-9 | Toggle widgets (1:CPU, 2:MEM, 3:GPU, 4:NET, 5:DISK, 6:SYS, 7:UP, 8:HLTH, 9:GATEWAY) | | Alt+1-9 | Pin/unpin widget to favorites row (max 4) | | w | Enter widget arrangement mode (drag-and-drop) | | Tab | Focus next widget | | Shift+Tab | Focus previous widget | | Enter | Show widget details (when widget focused) |

Session Controls

| Key | Action | |-----|--------| | f | Toggle favorite on current session | | F | Show favorites only (filter) | | g | Go to first page | | G | Retry gateway connection | | / | Search/filter sessions | | Return | Show session detail |

Data & Export

| Key | Action | |-----|--------| | e | Export dashboard data (JSON/CSV) | | E | Cycle export format | | Ctrl+S | Export snapshot (shareable config) | | Ctrl+O | Import snapshot | | X | Retry failed widgets (error recovery) |

Navigation

| Key | Action | |-----|--------| | ↑/k | Previous session | | ↓/j | Next session | | ←/h | Previous page | | →/l | Next page | | [/] | Previous/next page | | Ctrl+B | Page up | | Ctrl+F | Page down |

Theme & Display

| Key | Action | |-----|--------| | t | Cycle theme (default/dark/high-contrast/ocean) | | T | Open theme selector |

Session Sorting

Press o to cycle through different ways to sort the sessions list:

• time (default): Most recently updated sessions first
• tokens: Sessions with highest token usage first
• idle: Sessions with longest idle time first
• name: Alphabetical order by agent name

⚙️ Settings

Press s to open the settings panel where you can customize:

• Refresh Interval: Toggle between 1s, 2s, 5s, or 10s
• Widget Visibility: Toggle individual widgets (1-9 keys)
• Widget Sizes: Choose small/medium/large/wide for each widget
• Export Schedule: Configure automated metric exports
• Version Check: Set interval for update checking (1h/6h/12h/24h/off)
• Plugin Config: Configure installed plugins
• Performance Metrics: Show/hide performance overlay in footer

Settings are automatically saved to ~/.openclaw/dashboard-settings.json and persist across sessions.

Disabled widgets show [Disabled] and skip data fetching, reducing CPU usage.

📦 Running Persistently

Option 1: Using screen

# Install screen
brew install screen

# Create a detached screen session
screen -dmS claw-dashboard bash -c 'clawdash'

# To reattach
screen -r claw-dashboard

# To detach: press Ctrl+A, then D

Option 2: Using tmux (Recommended)

# Install tmux
brew install tmux

# Create a new tmux session
tmux new-session -d -s claw-dashboard 'clawdash'

# To attach
tmux attach -t claw-dashboard

# To detach: press Ctrl+B, then D

Option 3: LaunchAgent (Auto-start on Boot)

# Copy the plist (included in package)
cp ~/node_modules/claw-dashboard/ai.openclaw.dashboard.plist ~/Library/LaunchAgents/

# Edit paths in the plist
nano ~/Library/LaunchAgents/ai.openclaw.dashboard.plist
# Change /Users/kdsmith/... to your home directory

# Load the service
launchctl load ~/Library/LaunchAgents/ai.openclaw.dashboard.plist

# Check status
launchctl list | grep openclaw.dashboard

Option 4: Using pm2

# Install pm2
npm install -g pm2

# Start with pm2
pm2 start claw-dashboard --name claw-dashboard

# Save config
pm2 save

# Auto-start on boot
pm2 startup

🔧 Troubleshooting

"command not found" after global install

# Ensure npm global bin is in your PATH
export PATH="$(npm root -g)/../bin:$PATH"

# Add to your shell profile for persistence
echo 'export PATH="$(npm root -g)/../bin:$PATH"' >> ~/.zshrc

Dashboard shows "Not Available" for OpenClaw

# Check if OpenClaw is running
openclaw gateway status

# Start if needed
openclaw gateway start

Display Issues

For best results, use a terminal that supports:

• 256 colors
• Unicode box-drawing characters
• TrueColor (optional)

Recommended: iTerm2, Kitty, Alacritty

📝 Dependencies

• blessed - Terminal UI framework
• blessed-contrib - Widgets (charts, tables, gauges)
• systeminformation - System stats
• chalk - Terminal colors

📚 Documentation

• CHANGELOG.md - Version history and release notes
• docs/API.md - Internal API documentation for modules
• TODO.md - Planned features and development roadmap
• FEATURES.md - Detailed feature documentation

🤝 Contributing

Issues and PRs welcome at github.com/openclaw/claw-dashboard

📜 License

MIT