Metadata-Version: 2.4
Name: opencode-dashboard-server
Version: 0.2.0
Summary: FastAPI aggregator over opencode's SQLite storage
Project-URL: Homepage, https://github.com/GCS-ZHN/opencode-dashboard
Project-URL: Repository, https://github.com/GCS-ZHN/opencode-dashboard
Project-URL: Issues, https://github.com/GCS-ZHN/opencode-dashboard/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: uvicorn<1,>=0.30

# opencode-dashboard-server

FastAPI aggregation backend for the [opencode-dashboard](https://github.com/GCS-ZHN/opencode-dashboard)
project. Reads opencode's local SQLite storage via the `opencode db` CLI and exposes a JSON + SSE
API for the dashboard front end.

## Install (PyPI)

```bash
pip install opencode-dashboard-server
```

Requires:

- **Python ≥ 3.10**
- **`opencode` CLI** on the same host — the server shells out to `opencode db "<SQL>"` and never
  opens the SQLite file directly (it's WAL-mode and actively written while opencode runs).

## Quick start

Run one aggregator per opencode host:

```bash
uvicorn app:app --port 8791
```

Run on more hosts with different ports (`8792`, `8793`, …) and list each in the front end's
`dashboard.yaml`. Environment switches:

- `DASHBOARD_CORS_ORIGINS` — comma-separated CORS allow-list (defaults to the loopback dev origins `localhost/127.0.0.1:5173` and `:4173`; tighten or widen for your deployment).
- `DASHBOARD_POLL_SECONDS` — SSE poll interval in seconds (default `5`).
- `OPENCODE_BIN` — path to the `opencode` binary if it's not on `PATH`.

## API

- `GET /health` — liveness
- `GET /overview` — whole-host aggregate (tokens by type + cost, session counts, `updatedAt`)
- `GET /projects` — per-project rollups
- `GET /projects/{id}` — one project's sessions (parent/child tree)
- `GET /sessions/{id}` — per-model breakdown for one session (handles mid-conversation model switches)
- `GET /stream` — SSE: `updated` events when the DB changes (polled ~5s)

JSON is camelCase, timestamps are epoch-ms. Full contract in the repo's `API.md`.

## From source (development)

```bash
git clone https://github.com/GCS-ZHN/opencode-dashboard
cd opencode-dashboard/server
uv sync          # install deps (fastapi, uvicorn) + dev (pytest, httpx)
uv run pytest    # run tests
uvx ruff check . # lint
```
