# OpenClaw Dashboard

A lightweight web dashboard for monitoring OpenClaw (Claude Code / ACP) sessions in real-time.

## Features

- **Session list** — all agents/sessions with status, model, token counts, cost, and last activity
- **Session detail** — full message timeline with collapsible tool calls and thinking blocks
- **Live tail** — WebSocket streaming of new events as they arrive
- **Filtering** — by agent, status (active/idle/deleted/reset), and free-text search
- **Auto-refresh** — session list refreshes every 10 seconds

## Stack

- **Backend**: Node.js + Express + ws (no database — reads `.jsonl` files directly)
- **Frontend**: Vanilla HTML/CSS/JS SPA (no framework, dark GitHub-style theme)

---

## Quick start

### 1. Local (Node.js)

```bash
npm install
node server.js
```

Open [http://localhost:3850](http://localhost:3850)

### 2. Docker Compose

```bash
docker compose up -d
```

Open [http://localhost:3850](http://localhost:3850)

---

## Configuration

| Variable      | Default                         | Description                    |
|---------------|---------------------------------|--------------------------------|
| `PORT`        | `3850`                          | HTTP/WS listen port            |
| `SESSIONS_DIR`| `/home/node/.openclaw/agents`   | Root directory of agent folders|

```bash
PORT=8080 SESSIONS_DIR=/path/to/agents node server.js
```

---

## Session file format

Sessions are read from:

```
$SESSIONS_DIR/
├── <agent>/
│   └── sessions/
│       ├── <uuid>.jsonl              # active or idle
│       ├── <uuid>.jsonl.deleted.*   # deleted (archived)
│       └── <uuid>.jsonl.reset.*     # reset (archived)
```

Each `.jsonl` file contains newline-delimited JSON events:

| Event type              | Description                         |
|-------------------------|-------------------------------------|
| `session`               | Session metadata (id, cwd)          |
| `message`               | User / assistant messages           |
| `model_change`          | Model switch                        |
| `thinking_level_change` | Thinking budget change              |
| `custom`                | Custom events (model-snapshot, etc.)|

---

## API

| Endpoint                         | Description                        |
|----------------------------------|------------------------------------|
| `GET /api/sessions`              | List all sessions (parsed summary) |
| `GET /api/sessions/:agent/:id`   | Full event log for one session     |
| `WS  /ws/sessions/:agent/:id`    | Live tail (streams new events)     |

---

## Deployment notes

- The Docker image runs as the `node` user (non-root).
- The sessions volume is mounted **read-only** (`ro`) — the dashboard never writes.
- `restart: unless-stopped` keeps the container running across reboots.