backboard-usage 0.1.0

Live token and cost visibility for Backboard apps. Run the server, open the UI, see usage in real time.

Backboard Usage

Live token and cost visibility for Backboard apps. See usage in real time as your agents run—no need to wait for the billing dashboard.

Install

pip install backboard-usage

Quick start

1. Start the usage server (one terminal, leave it running):

   backboard-usage-server
   

2. Open the UI in your browser: http://localhost:8766

3. Run your Backboard app in another terminal. Your app must send usage data to ws://localhost:8765 in the expected JSON format (e.g. using the pattern in the example below).

You’ll see live tokens, cost, and breakdown by agent and model. Run history is stored in the browser (last 10 runs).

Wire format

Your app connects to the WebSocket and sends JSON messages.

During a run (after each message or step):

{
  "event": "usage",
  "total_tokens": 1234,
  "total_cost": 0.0123,
  "by_agent": {
    "Idea Analyzer": { "tokens": 600, "cost": 0.006 },
    "Market Researcher": { "tokens": 634, "cost": 0.0063 }
  },
  "by_model": {
    "openai/gpt-4o": { "tokens": 1234, "cost": 0.0123 }
  }
}

When the run finishes:

{
  "event": "done",
  "total_tokens": 1234,
  "total_cost": 0.0123,
  "by_agent": { ... },
  "by_model": { ... }
}

The UI shows “This run” (current session), “Total (all runs)” (aggregate from history), and “Run history” (last 10 runs).

Example: Python

Use the Backboard SDK and send usage after each add_message (tokens/cost from the response, or estimate with backboard_usage.cost.estimate_cost). Connect to ws://localhost:8765 and push the JSON above. See orchestrator.py in this repo for a full example with multiple agents.

Optional env

Variable	Default	Description
USAGE_WS_URL	ws://localhost:8765	WebSocket URL your app uses.

Development from repo

pip install -e .
# Build UI (first time or after UI changes):
cd usage-ui && npm ci && npm run build && cd ..
# Copy UI into package (so server serves it):
# Windows PowerShell:
Copy-Item -Path usage-ui\dist\* -Destination backboard_usage\ui -Recurse -Force
# Then run:
backboard-usage-server
# Or: python usage_server.py

License

MIT