Screenshots

Features

Web Dashboard

• Real-time monitoring of all Claude Code sessions via WebSocket
• Project-based organization — Sessions grouped by working directory
• Live status indicators — See which sessions are busy, idle, or waiting for input
• One-click navigation — Jump to any session instantly

Syntax Highlighting

• Color-coded terminal output — User prompts, Claude responses, tool calls, and results
• Tool-specific colors — Different colors for Read, Write, Edit, Bash, Task, and more
• Diff highlighting — Green for additions, red for removals in file edits
• Toggleable theming — Switch between styled and raw output

Mobile-First Design

• Fully responsive — Works on desktop, tablet, and phone
• Touch-friendly controls — Large buttons for common actions
• Quick action toolbar — Send keys (Up, Down, Tab, Esc, Ctrl-C) with one tap

Session Control

• Send text input — Type messages directly to Claude
• Keyboard shortcuts — Send special keys and key combinations
• Terminal resize — Fit tmux pane to browser viewport
• Kill sessions — Terminate Claude processes when needed

Optional Features

• Authentication — Password-protect your dashboard
• LAN access — Monitor sessions from any device on your network

Installation

From npm/bun (recommended)

bun install -g claude-mux
# or: npm install -g claude-mux

From source

git clone https://github.com/christinoleo/claude-mux.git
cd claude-mux
bun install
bun run build
bun link  # Makes 'claude-mux' available globally

Quick Start

1. Run setup

claude-mux setup

This will:

• Create the data directory at ~/.claude-watch/
• Install Claude Code hooks in ~/.claude/settings.json

2. Start the web server

claude-mux serve --port 3456 --host 0.0.0.0

3. Open the dashboard

Navigate to http://localhost:3456 (or your machine's IP for LAN access).

4. Start using Claude Code

Any Claude Code session started after setup will appear in the dashboard automatically.

Web Interface

Dashboard

The main dashboard shows all active Claude Code sessions organized by project:

| Element | Description | |---------|-------------| | Project cards | Sessions grouped by working directory | | Status indicators | Busy, Idle, Waiting for input | | Current action | Shows what Claude is currently doing | | Quick actions | New session, kill session, refresh |

Session View

Click any session to open the real-time terminal view:

| Feature | Description | |---------|-------------| | Live output | Streams terminal content via WebSocket | | Syntax highlighting | Color-coded messages and tool calls | | Text input | Send messages to Claude | | Action buttons | Up, Down, Space, Tab, Esc, Ctrl-C, etc. | | Tmux command | Copy tmux attach command for direct access |

Keyboard Shortcuts (in session view)

| Key | Action | |-----|--------| | Enter | Send message | | Shift+Enter | New line in message |

CLI Commands

| Command | Description | |---------|-------------| | claude-mux serve | Start the web server | | claude-mux setup | Run interactive setup wizard | | claude-mux uninstall | Remove hooks and configuration | | claude-mux | Start TUI dashboard (legacy, requires tmux) |

Server Options

claude-mux serve [options]

Options:
  -p, --port <number>     Port to listen on (default: 45677)
  -h, --host <string>     Host to bind to (default: "localhost")
  -a, --auth <password>   Enable authentication with password

Examples

# Start on custom port
claude-mux serve --port 8080

# Allow LAN access
claude-mux serve --host 0.0.0.0

# With authentication
claude-mux serve --host 0.0.0.0 --auth mysecretpassword

How It Works

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Claude Code    │────▶│  Hook Scripts    │────▶│  JSON Files     │
│  (running)      │     │  (on events)     │     │  (~/.claude-watch/sessions/)
└─────────────────┘     └──────────────────┘     └────────┬────────┘
                                                          │
┌─────────────────┐     ┌──────────────────┐              │
│  tmux panes     │────▶│  Pane Capture    │──────────────┤
│  (terminal)     │     │  (WebSocket)     │              │
└─────────────────┘     └──────────────────┘              │
                                                          ▼
                        ┌──────────────────┐     ┌─────────────────┐
                        │  Web Browser     │◀───▶│  SvelteKit      │
                        │  (dashboard)     │     │  (WebSocket)    │
                        └──────────────────┘     └─────────────────┘

Claude Code Hooks

claude-mux uses Claude Code hooks to track session state:

| Hook | Purpose | |------|---------| | SessionStart | Register new session with PID and working directory | | UserPromptSubmit | Mark session as busy | | PreToolUse | Update status with current tool name | | Stop | Mark session as idle when turn ends | | Notification | Handle permission requests and questions |

Real-time Updates

• WebSocket connections for instant updates (no polling)
• File watcher monitors session state changes
• Pane capture streams terminal output every 200ms

Terminal UI (Legacy)

claude-mux also includes a terminal-based dashboard for use inside tmux:

claude-mux  # Requires tmux

| Key | Action | |-----|--------| | j / ↓ | Move selection down | | k / ↑ | Move selection up | | Enter | Jump to selected session | | q | Quit dashboard |

Press prefix + W from any tmux session to jump to the dashboard.

Development

Prerequisites

• Node.js >= 18 (or Bun)
• tmux (for full functionality)

Setup

git clone https://github.com/christinoleo/claude-mux.git
cd claude-mux
bun install

Development Server

bun run dev:serve  # Starts Vite dev server with HMR

Build

bun run build      # Build CLI + web app
bun run build:cli  # Build CLI only
bun run build:web  # Build web app only

Testing

bun test           # Run tests
bun run lint       # Lint code
bun run format     # Format code

Project Structure

claude-mux/
├── src/                    # CLI and hooks
│   ├── cli.ts              # Entry point
│   ├── commands/           # CLI commands (serve, setup, tui)
│   ├── hooks/              # Claude Code hook handler
│   └── server/             # File watcher, WebSocket handlers
├── web/                    # SvelteKit web app
│   ├── src/
│   │   ├── lib/
│   │   │   ├── components/ # UI components
│   │   │   ├── stores/     # Svelte stores (sessions, terminal, preferences)
│   │   │   └── utils/      # Terminal parser, helpers
│   │   └── routes/         # Pages and API routes
│   └── svelte.config.js
└── docs/
    └── images/             # Screenshots

Troubleshooting

Sessions not appearing

1. Ensure you ran claude-mux setup to install hooks
2. Restart any running Claude Code sessions (hooks are loaded at startup)
3. Check that ~/.claude/settings.json contains claude-mux hooks

Cannot connect from another device

1. Use --host 0.0.0.0 to allow external connections
2. Check your firewall allows the port
3. Use your machine's LAN IP, not localhost

Status not updating

1. Check hooks are installed: grep claude-mux ~/.claude/settings.json
2. Restart Claude Code sessions to pick up new hooks

Requirements

• Bun >= 1.0 (required for the web server)
• tmux (required for terminal capture)
• Claude Code with hooks support

Note: The claude-mux serve command requires Bun runtime.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run tests (bun test)
4. Commit your changes
5. Push to the branch
6. Open a Pull Request