Getting Started
This guide covers installation and basic usage of Claude Session Tools.
Prerequisites
Before installing Claude Session Tools, ensure you have:
- Node.js 18 or later installed
- loggable-session CLI tool configured and working
- At least one Claude Code session running via loggable-session
Installation
Clone the repository and install dependencies:
cd claude-monitor/app
npm install
Running the Application
Development Mode
Start both the server and client with hot module replacement:
npm run dev
This starts:
- Express server on port 3000
- Vite development server on port 5173
Open your browser to http://localhost:5173 to access the web interface.
Production Mode
Build and run the production server:
npm run build
npm run build:server
npm start
Access the application at http://localhost:3000.
Basic Usage
Step 1: Start a Claude Code Session
Use loggable-session to start a Claude Code session with logging enabled:
logsession start my-project
This creates a tmux session and begins logging terminal output.
Step 2: Add Session to Monitor
In the web interface:
- Enter the session name (e.g.,
my-project) in the input field - Click "Create & Watch"
- A session card appears showing the current status
Step 3: Monitor Session Status
The session card displays:
- Primary status: The main state (idle, active, waiting, stuck, dead)
- Detail: Additional context about the current activity
- Health: Overall health indicator (ALIVE, STUCK, DEAD, RECOVERED)
- Timestamp: Last update time
Step 4: Configure Sound Notifications (Optional)
Click the settings icon on a session card to configure:
- Enable/disable wait notifications
- Enable/disable idle notifications
- Set threshold durations
- Choose between generated sounds or ambient music
- Adjust volume
Development Commands
| Command | Description |
|---|---|
npm run dev | Start both server and client in development mode |
npm run dev:server | Start only the Express server (with tsx watch) |
npm run dev:client | Start only the Vite development server |
npm run build | Build the client for production |
npm run build:server | Build the server for production |
npm start | Run the production server |
Directory Structure
app/
├── src/
│ ├── lib/ # Core logic
│ │ ├── LogWatcher.ts # File system watcher
│ │ ├── StatusDetector.ts # Status detection engine
│ │ ├── ambientSound.ts # Sound management
│ │ └── types.ts # TypeScript types
│ ├── components/ # React components
│ ├── hooks/ # React hooks
│ ├── App.tsx
│ └── main.tsx
├── server.ts # Express + WebSocket server
├── package.json
└── vite.config.ts
Troubleshooting
Port Conflicts
If port 5173 is in use, modify vite.config.ts:
server: {
port: 5174
}
Session Not Detected
Verify the session exists:
logsession list
Ensure the session was started with loggable-session, not plain tmux.
WebSocket Connection Errors
Check that the Express server is running on port 3000. The client expects the WebSocket endpoint at ws://localhost:3000.