megaproxy
71a60ab054
Server (SvelteKit + SQLite Docker container) + per-machine agent that parses Claude Code JSONL transcripts. docker-compose one-command deploy; raw transcript view + search gated behind SHOW_TRANSCRIPTS (hidden by default). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
101 lines
3.9 KiB
Markdown
101 lines
3.9 KiB
Markdown
# toknmtr
|
|
|
|
Self-hosted **Claude Code usage & analytics dashboard**. An **agent** on each of your
|
|
machines parses Claude Code's JSONL transcripts into a full event log and pushes it to a
|
|
**server** (one SvelteKit + SQLite container). The server stores everything — usage, tool
|
|
calls, commands, raw prompts/responses — and serves a dashboard plus a full-text-searchable
|
|
session archive.
|
|
|
|
It's two halves:
|
|
|
|
- **Server** (`src/`, shipped as a Docker image) — the dashboard, the ingest API, the DB.
|
|
- **Agent** (`agent/` + `ops/`, runs on each machine) — parses `~/.claude/projects/**/*.jsonl`
|
|
and POSTs to the server. Not part of the image; you run it wherever you use Claude Code.
|
|
|
|
The server image contains **no data** — the SQLite DB is created empty in a mounted volume on
|
|
first run. All conversation content only ever comes from *your* agent pushing *your*
|
|
transcripts to *your* server.
|
|
|
|
> **New here? Follow [DEPLOY.md](DEPLOY.md)** — a full step-by-step walkthrough (prerequisites,
|
|
> server, agent, security, updating). The sections below are the quick reference.
|
|
|
|
---
|
|
|
|
## 1. Run the server (Docker)
|
|
|
|
Requires Docker with the Compose plugin. From the repo root:
|
|
|
|
```sh
|
|
cp .env.example .env
|
|
# edit .env: set API_TOKEN to a long random secret
|
|
# openssl rand -hex 32
|
|
docker compose up -d --build
|
|
```
|
|
|
|
The dashboard is now at **http://localhost:3001**. The DB lives in the `toknmtr-data`
|
|
Docker volume; the container restarts unless stopped.
|
|
|
|
**Privacy note — the dashboard has no auth.** By default the two surfaces that expose
|
|
verbatim prompt/response text (the per-session **transcript view** and full-text **search**)
|
|
are **hidden**; charts, KPIs, and session metadata stay visible. Only set
|
|
`SHOW_TRANSCRIPTS=true` in `.env` once you've put the dashboard behind auth (reverse proxy,
|
|
VPN, etc.). Don't expose it to the public internet as-is.
|
|
|
|
### Config (`.env`)
|
|
|
|
| Var | Purpose |
|
|
| ------------------ | --------------------------------------------------------------- |
|
|
| `API_TOKEN` | **Required.** Bearer token the agent must send to `/api/ingest`. |
|
|
| `SHOW_TRANSCRIPTS` | `true` reveals transcript view + search. Unset = hidden (safe). |
|
|
| `PORT` | Host port is set in `docker-compose.yml` (`3001:3000`). |
|
|
|
|
---
|
|
|
|
## 2. Feeding it data (the agent)
|
|
|
|
The server starts empty. To populate it, run the agent on each machine where you use Claude
|
|
Code (needs Node 24+ for `--experimental-strip-types`). One-time setup per machine:
|
|
|
|
```sh
|
|
mkdir -p ~/.toknmtr
|
|
cat > ~/.toknmtr/env <<'EOF'
|
|
TOKNMTR_URL=http://<server-host>:3001
|
|
TOKNMTR_TOKEN=<the same API_TOKEN you set on the server>
|
|
EOF
|
|
chmod 600 ~/.toknmtr/env
|
|
```
|
|
|
|
Then, from a clone of this repo on that machine:
|
|
|
|
```sh
|
|
# one-time: ingest all transcripts already on disk
|
|
node --experimental-strip-types agent/run.ts --backfill
|
|
|
|
# ongoing capture — register the Stop hook so every turn pushes incrementally
|
|
ops/install-hook.sh
|
|
```
|
|
|
|
`ops/install-hook.sh` adds a near-zero-cost Claude Code `Stop` hook (additive + reversible
|
|
with `--remove`). An optional `ops/install-cron.sh` adds a reconcile sweep as a safety net.
|
|
Full agent/capture docs — the `~/.toknmtr/env` format, the hook-vs-cron tradeoff, backfill,
|
|
and troubleshooting — are in **[`ops/README.md`](ops/README.md)**.
|
|
|
|
Ingest is an idempotent upsert (keyed on `host + session_id + uuid`), so re-running the
|
|
backfill or overlapping hook/cron sweeps never duplicates data.
|
|
|
|
---
|
|
|
|
## 3. Development
|
|
|
|
Node 24, SvelteKit 2 (Svelte 5), TypeScript, `better-sqlite3`.
|
|
|
|
```sh
|
|
npm install
|
|
npm run dev # dev server
|
|
npm run check # typecheck
|
|
npm run build # production build → build/ (run with `node build`)
|
|
npm run lint # prettier + eslint
|
|
```
|
|
|
|
Pricing lives server-side in `src/lib/server/pricing.ts` — adding a model is a one-line
|
|
update. Because the subscription is flat-rate, all `$` figures are *notional* (API-equivalent).
|