npm package: @gilangjavier/oc-dashboard
Description: localhost-only OpenClaw observability dashboard with a calm modern game-HUD UI
Author: Gilang Javier
Latest version: 0.2.0

# OpenClaw Dashboard 🎮

> A localhost-only OpenClaw observability dashboard with a calm modern game-HUD aesthetic.

![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
![npm version](https://img.shields.io/npm/v/@gilangjavier/oc-dashboard.svg)

This CLI tool starts a local web server that displays OpenClaw cron jobs and their run history in a calmer modern HUD-styled dashboard. It's designed for quick local monitoring only — no internet, no cloud, just you and your cron jobs.

---

## For AI agents

```bash
# Install
npm i -g @gilangjavier/oc-dashboard

# Run with defaults (reads ~/.openclaw)
oc-dashboard

# Custom OpenClaw home
OPENCLAW_HOME=/custom/path/.openclaw oc-dashboard

# Custom port
oc-dashboard --port 8080
```

Then open http://localhost:3000 in your browser. Dashboard auto-refreshes every 5 seconds.

Data sources:
- `cron/jobs.json` → list of cron jobs + live execution marker (`state.runningAtMs`)
- `cron/runs/*.jsonl` → recent finished run records
- `subagents/runs.json` → spawned sub-agent runs

The server exposes `/api/data` (JSON) and `/health`. No authentication. Stops when you Ctrl+C.

---

## For humans

### What it does

OpenClaw Dashboard is a calm, game-inspired web app that shows you the status of your OpenClaw cron jobs at a glance. Think of it as a game监控 station for your automation tasks.

- **All Jobs view** — shows every configured job with its last run, next scheduled run, duration, and error count
- **Filter tabs** — quickly see only running jobs or those with errors
- **Live running marker** — as soon as OpenClaw sets `runningAtMs`, the job flips to `RUNNING` and gets a live in-progress history row
- **Job Details** — click any job to see its latest run summary and command
- **Sub-Agents tab** — view spawned sub-agent sessions/runs (status, model, child session, timing)
- **Auto-refresh** — updates every 5 seconds so you see real-time changes

The UI now uses a modern HUD look with calmer colors, cleaner spacing, and smoother surfaces to reduce eye strain during long monitoring sessions.

### Installation

As an npm package (global CLI):

```bash
npm install -g @gilangjavier/oc-dashboard
```

Or as a dev dependency in your own project:

```bash
npm install --save-dev @gilangjavier/oc-dashboard
```

### Quick start

1. Make sure OpenClaw is installed and has cron jobs set up (by default at `~/.openclaw`)
2. Run the dashboard:

```bash
oc-dashboard
```

3. Open your browser to http://localhost:3000

That's it. No config file, no database, no OAuth. It just reads your existing OpenClaw files and shows them in a fun interface.

### Customizing the OpenClaw home

If your OpenClaw home is somewhere else:

```bash
export OPENCLAW_HOME=/my/custom/path
oc-dashboard
```

Or use the flag:

```bash
oc-dashboard --home /my/custom/path
```

### Changing the port

```bash
oc-dashboard --port 8080
```

Or set `PORT` environment variable.

### Data it reads

The dashboard expects the standard OpenClaw cron layout:

```
OPENCLAW_HOME/
├── cron/
│   ├── jobs.json           # list of jobs
│   └── runs/
│       ├── 2024-01-15.jsonl
│       └── 2024-01-16.jsonl
└── subagents/
    └── runs.json           # spawned sub-agent run history
```

`jobs.json` format (example):

```json
[
  {
    "id": "backup-db",
    "name": "Database Backup",
    "schedule": "0 2 * * *",
    "command": "/usr/local/bin/backup-db",
    "enabled": true,
    "last_run": 1705315200000,
    "last_status": "success",
    "last_duration": 45000,
    "consecutive_errors": 0
  }
]
```

Run files (`*.jsonl`) contain one JSON object per line:

```json
{"job_id":"backup-db","timestamp":1705315200000,"status":"success","duration":45000,"summary":"Backup completed"}
```

If these files don't exist, the dashboard will show "No jobs found" — check your OpenClaw setup.

### Security note

This server binds to `localhost` only and has no authentication. It's meant for single-user local monitoring. Do not expose it to the network.

### Troubleshooting

- **No jobs showing?** Check that `OPENCLAW_HOME/cron/jobs.json` exists and contains valid JSON.
- **Port already in use?** Use `--port` to pick another.
- **Permission denied?** Make sure you have read access to your OpenClaw home directory.

### Development

```bash
git clone https://github.com/gilangjavier/oc-dashboard.git
cd oc-dashboard
npm install
npm run build
npm start
```

Run tests:

```bash
npm test
```

### Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for both:
- **For AI agents**
- **For humans**

## License

MIT © Gilang Javier

---

**Enjoy your calmer cron monitoring!** ✨⚡