claude-sessions-ui

A browser-based dashboard for managing all your Claude Code agent sessions without switching terminals.

Features

• View all Claude Code sessions across projects in one place
• Live status indicators — see which sessions are working, waiting, or idle
• Live tool activity — see the current tool being executed (Edit, Bash, Grep, etc.)
• Chat with any session directly from the dashboard
• Built-in terminal — connect to any session's PTY in a split-panel view
• Launch new sessions into an external terminal (Windows Terminal on WSL, iTerm2/Terminal.app on macOS)
• Group sessions by status or project, collapse/expand groups
• Search and filter by project, title, or path
• Read/unread tracking — sessions highlight when they need your attention
• Desktop notifications when a session is waiting for input
• Themes: Phosphor, Amber, Ice, Mono, Paper
• Scalable UI font size and separate terminal font size
• Skip permissions mode — launch sessions with --dangerously-skip-permissions

Requirements

• Node.js >= 18
• Claude Code CLI installed and authenticated
• Windows/WSL: Windows Terminal (wt.exe) must be installed for the "open in terminal" feature
• macOS: iTerm2 or Terminal.app

Install

Global install (recommended)

npm install -g claude-sessions-ui

Then run from anywhere:

claude-sessions-ui

Opens the dashboard at http://localhost:3333.

npx (no install)

npx claude-sessions-ui

Custom port

claude-sessions-ui --port 8080

Development

Clone the repo and install dependencies:

git clone https://github.com/adepuit/claude-sessions-ui.git
cd claude-sessions-ui
npm install
npm run dev

This starts the Vite dev server (frontend) and Express backend concurrently. Open http://localhost:5173.

Publishing to npm

npm run build   # builds frontend into dist/
npm publish     # ships server.js + dist/ only

The prepare script runs vite build automatically before publish.

How it works

• Session data: reads ~/.claude/projects/*/[id].jsonl files — the same files Claude Code writes to
• Live updates: uses Server-Sent Events (SSE) to stream new activity as it's written to disk
• Terminal: spawns claude --resume <id> in a PTY via node-pty, streamed over WebSocket to an xterm.js terminal in the browser
• Chat: runs claude --resume <id> -p "message" --output-format stream-json and streams the response
• PID detection: checks ~/.claude/sessions/*.json, then scans ps aux for live claude --resume processes
• Status:
  • Working — Claude is actively processing or executing tools
  • Waiting — Claude is waiting for user input
  • Idle — session is open but inactive

Project structure

server.js          # Express backend — API routes, session parsing, SSE, PTY management
src/
  App.jsx          # Main layout, state, grouping, session ordering
  components/
    SessionCard.jsx     # Individual session card (full, compact, and mini variants)
    SessionPanel.jsx    # Split-view right panel wrapper
    TerminalPanel.jsx   # xterm.js PTY terminal
    ProjectFilter.jsx   # Project picker and filter bar
    StatusBadge.jsx     # Working/Waiting/Idle pill
    SettingsPanel.jsx   # Font size, theme, and Claude flags settings
    NewSessionPanel.jsx # Launch a new Claude session
  themes/
    phosphor.js    # Default green-on-dark theme
    amber.js       # Amber theme
    ice.js         # Blue/ice theme
    mono.js        # Monochrome theme
    paper.js       # Light theme

Platform notes

Windows + WSL

The dashboard runs inside WSL. The "open in terminal" button launches a new Windows Terminal tab via wt.exe directly into your WSL session.

macOS

Full support. Launching a new session uses AppleScript to open a new tab in iTerm2 (preferred) or Terminal.app. The built-in terminal panel uses prebuilt node-pty binaries via @homebridge/node-pty-prebuilt-multiarch.

Linux (native)

Falls back to x-terminal-emulator for launching terminals.