OpenCode TokenSpeed Monitor

TokenSpeed Monitor is an OpenCode plugin that measures token speed per request, stores metrics in SQLite, and exposes data over local and hub HTTP APIs.

Compatibility

• Tested against @opencode-ai/plugin 1.2.x

• Package peer dependency: @opencode-ai/plugin@^1.2.2

• This plugin uses stable core plugin APIs (Plugin, PluginInput, tool, ToolDefinition) and avoids experimental hooks

• npm: https://www.npmjs.com/package/opencode-tokenspeed-monitor

• GitHub: https://github.com/Daltonganger/opencode-tokenspeed-monitor

Features

• Tracks token usage from OpenCode events (message.updated, message.part.updated, session.idle)
• Calculates output TPS and total TPS per completed request
• Persists request/session/model/provider/project data in local SQLite
• Exposes local dashboard + REST + SSE endpoints
• Supports anonymous upload queue with signed ingest payloads
• Adds in-app commands for status, history, stats, and background mode

Commands

• /ts - open TokenSpeed local dashboard in browser (/)
• /ts-toggle - toggle monitor on/off
• /ts-status - show current status and latest metric
• /ts-stats - show aggregated totals and model summary
• /ts-history - show recent request history (supports limit)
• /ts-bg - start/stop background API mode
• /ts-upload - show upload queue status and hub configuration
• /ts-upload-flush - trigger upload queue flush immediately

These slash commands are shipped in the plugin commands/ directory, so they are available to users after plugin install.

API Endpoints

When plugin background API is active, the plugin serves:

• GET /api/stats
• GET /api/stats/models
• GET /api/stats/providers
• GET /api/projects
• GET /api/history?limit=10
• GET /api/sessions?limit=10
• GET /api/live (SSE stream)
• GET /api/upload/status
• GET /api/upload/queue?limit=20
• POST /api/upload/flush

Installation

Option A: Install from npm (short plugin line)

After publishing to npm, add this to your OpenCode config (~/.config/opencode/opencode.json):

{
  "plugin": [
    "opencode-tokenspeed-monitor@latest"
  ]
}

Then restart OpenCode.

Option B: Install from GitHub

Add this to your OpenCode config (~/.config/opencode/opencode.json) using the latest release tag:

{
  "plugin": [
    "github:Daltonganger/opencode-tokenspeed-monitor#v0.1.8"
  ]
}

Then restart OpenCode.

Option C: Local development install

1. Build the plugin:

bun install
bun run build

2. Add plugin path to your OpenCode config (~/.config/opencode/opencode.json):

{
  "plugin": [
    "/absolute/path/to/opencode-tokenspeed-monitor"
  ]
}

3. Restart OpenCode.

Configuration

• TS_BG_PORT (optional): local dashboard/API port (default: 3456)
• TS_DB_PATH (optional): explicit local SQLite database path
• OPENCODE_HOME (optional): OpenCode home directory; default storage under ~/.local/share/opencode/tokenspeed-monitor/
• TS_UPLOAD_ENABLED (optional): enable upload dispatcher (1/true/on). Default: on (set 0/false/off to disable).
• TS_HUB_URL (optional): hub ingest base URL. Default: https://tokenspeed.2631.eu
• TS_HUB_SIGNING_KEY (optional): explicit signing key used for hub request signatures
• TS_HUB_INVITE_TOKEN (optional): invite token for protected /v1/devices/register; not required for auto-bootstrap
• TS_HUB_ANON_USER_ID (optional): override anonymous user ID used for hub onboarding/filtering
• TS_HUB_DEVICE_ID (optional): explicit device identifier override
• TS_HUB_DEVICE_LABEL (optional): device label sent during registration
• TS_UPLOAD_INTERVAL_SEC (optional): upload dispatcher interval in seconds (default 30)
• TS_UPLOAD_BUCKET_SEC (optional): queue aggregation bucket size in seconds (default 300)
• TS_ANON_SALT_PATH (optional): custom path for local anonymization salt file
• TS_HUB_PORT (hub server, optional): hub listen port (default 3476)
• TS_HUB_DB_PATH (hub server, optional): custom hub SQLite path
• TS_HUB_ADMIN_TOKEN (hub server, optional): admin token for /admin and /v1/devices*
• TS_HUB_ADMIN_LOGIN_WINDOW_SEC (hub server, optional): failed login window in seconds (default 300)
• TS_HUB_ADMIN_LOGIN_MAX_ATTEMPTS (hub server, optional): max failed login attempts per source IP in the window (default 10)

Example:

TS_BG_PORT=4567 opencode

Usage

In OpenCode:

/ts
/ts-status
/ts-stats
/ts-history
/ts-bg
/ts-upload
/ts-upload-flush

In terminal (while /ts-bg is ON):

PORT=${TS_BG_PORT:-3456}
curl "http://localhost:${PORT}/api/stats"
curl "http://localhost:${PORT}/api/stats/models"
curl "http://localhost:${PORT}/api/stats/providers"
curl "http://localhost:${PORT}/api/projects"
curl "http://localhost:${PORT}/api/history?limit=10"
curl "http://localhost:${PORT}/api/sessions?limit=10"
curl "http://localhost:${PORT}/api/upload/status"
curl "http://localhost:${PORT}/api/upload/queue?limit=20"
curl -X POST "http://localhost:${PORT}/api/upload/flush"
curl -N --max-time 8 "http://localhost:${PORT}/api/live"

Development

bun run lint
bun run format
bun run test
bun run build

Quality automation

• GitHub Actions runs lint, test, and build on pushes and pull requests
• Dependabot checks Bun dependencies and GitHub Actions weekly
• Run npm run release:check before publishing a new release

Hub server (optional)

Start a minimal signed ingest + dashboard API hub:

TS_HUB_SIGNING_KEY="legacy-shared-key" TS_HUB_INVITE_TOKEN="register-token" TS_HUB_ADMIN_TOKEN="admin-token" bun run hub:start

Docker / Dockge

This repo includes a ready Dockge stack file: docker-compose.dockge.yml.

1. Copy env template and set real secrets:

cp .env.dockge.example .env

2. In Dockge, create a stack using docker-compose.dockge.yml.
3. Set TS_HUB_ADMIN_TOKEN. TS_HUB_INVITE_TOKEN is optional and only needed if you want protected manual registration.
4. Start the stack.

Local Docker CLI alternative:

docker compose -f docker-compose.dockge.yml up -d --build

Auto deploy to 2631US

For your VPS alias (2631US in ~/.ssh/config), use the built-in deploy script:

npm run deploy:2631us

Optional overrides:

TARGET_HOST=2631US TARGET_DIR=/opt/stacks/tokenspeed-hub BRANCH=main npm run deploy:2631us

The script will pull latest code on the server, run docker compose up -d --build, and verify /v1/health.

Open dashboard in browser:

http://localhost:3476/

Open admin page in browser:

http://localhost:3476/admin

Note: /admin now requires TS_HUB_ADMIN_TOKEN. Open the page and submit the token in the login form, or send it via X-TS-Admin-Token/Authorization: Bearer headers for API calls.

Hub endpoints:

• GET /v1/health
• POST /v1/devices/bootstrap (auto-onboarding; returns deviceId, anonUserId, signingKey)
• POST /v1/devices/register
• GET /v1/devices (admin token required)
• POST /v1/devices/revoke (admin token required)
• POST /v1/devices/activate (admin token required)
• POST /v1/devices/bulk (admin token required, action=revoke|activate)
• POST /v1/ingest/buckets
• GET /v1/dashboard/summary?from=&to=&providerId=&modelId=&anonProjectId=&deviceId=&anonUserId=
• GET /v1/dashboard/models?from=&to=&limit=&providerId=&modelId=&anonProjectId=&deviceId=&anonUserId=
• GET /v1/dashboard/providers?from=&to=&limit=&providerId=&modelId=&anonProjectId=&deviceId=&anonUserId=
• GET /v1/dashboard/projects?from=&to=&limit=&providerId=&modelId=&anonProjectId=&deviceId=&anonUserId=
• GET /v1/dashboard/timeseries?metric=tokens|cost|tps&groupBy=hour|day&from=&to=&providerId=&modelId=&anonProjectId=&deviceId=&anonUserId=
• GET /v1/dashboard/export.csv?from=&to=&providerId=&modelId=&anonProjectId=&deviceId=&anonUserId=
• GET /v1/dashboard/export.json?from=&to=&providerId=&modelId=&anonProjectId=&deviceId=&anonUserId=&groupBy=hour|day

Deployment guide: DEPLOYMENT-HUB.md

Example onboarding + admin calls:

HUB=http://localhost:3476

curl -X POST "$HUB/v1/devices/register" \
  -H 'Content-Type: application/json' \
  -d '{"deviceId":"dev_local","label":"My Laptop","inviteToken":"register-token"}'

curl "$HUB/v1/devices?limit=20" \
  -H 'X-TS-Admin-Token: admin-token'

curl -X POST "$HUB/v1/devices/revoke" \
  -H 'Authorization: Bearer admin-token' \
  -H 'Content-Type: application/json' \
  -d '{"deviceId":"dev_local"}'

Publish to npm

npm run release:check
npm login
npm publish --access public

If you also want GitHub installs by tag to point at the same release, push the matching git tag as well.

Release checklist: RELEASE.md

After publish, users can use:

{
  "plugin": [
    "opencode-tokenspeed-monitor@latest"
  ]
}

Notes

• Local database defaults to ~/.local/share/opencode/tokenspeed-monitor/tokenspeed-monitor.sqlite.
• Legacy ./data/tokenspeed-monitor.sqlite is auto-migrated when possible.