Sessions Usage and Budgets

Sessions, Usage and Budgets

Nautelle records every agent session on every runner — fleet workers, the orchestrator, skill runs, Board card workers and the sessions you start yourself in a terminal — and prices every LLM request it made. You see what ran, what it cost, and you can cap spend before it surprises you. This page covers the session view, how cost is computed, the Usage screen and budgets.

flowchart LR
  t["Claude Code transcripts<br/>(runner tails them)"] --> ev["llm.request events"]
  o["OpenTelemetry logs<br/>127.0.0.1:4318"] --> ev
  ev --> api["API: sessions tree"]
  api --> price["Price at ingest<br/>(current price version)"]
  price --> roll["Hourly rollups"]
  roll --> usage["Usage screen"]
  roll --> budget{"Budget<br/>thresholds"}
  budget -->|alert| notify["Notification"]
  budget -->|stop| gate["New runs refused<br/>409 budget_exceeded"]

Loading

Sessions

Open Sessions (/sessions). Each session lists its project, runtime, model, tokens, cost and an origin badge:

Origin	What started it
Worker	a fleet slot or a Board card worker
Run	a runner run: a skill, a schedule, design, planner
Manual	you, in your own terminal
Unknown	not correlated yet

Open a session for its tree: turns → LLM requests, tool calls and subagents, each with its tokens and API-equivalent cost. A manual session also shows its live state (working, waiting for you, idle) from Claude Code hooks, and an admin can attach to it from here.

How sessions are found. The runner tails Claude Code transcripts for every runtime profile on the machine and correlates each session to a project by its working directory, and to a slot by its worktree. Sessions outside any connected project are visible to admins only.

Note

Codex sessions are listed, but their transcripts are not parsed yet. Codex token usage over OpenTelemetry is experimental and off by default.

Session content is opt-in

By default only metadata leaves the machine: names, ids, timing and token counts — never prompts, replies, tool inputs or outputs. An admin can turn on content per project under Project › Settings › Sessions:

• content comes only from Claude Code hook payloads, and only for sessions correlated to that project;
• it is redacted on the runner before it is sent (tokens, keys, Authorization headers, .env assignments, private-key blocks) and capped at 16 KiB per text;
• it is kept for a retention period you choose (default 30 days, 1–365);
• every project member, viewers included, can read it; only an admin can purge it.

Session content also powers Capture of follow-up work from manual sessions.

Workflows

Workflows (/workflows) looks across root sessions instead of one at a time: how sessions flow from the main agent through subagent types and compactions to an outcome, which tool follows which within a turn (with error share), and a set of summary figures, each with its definition. Click a node to filter the page.

Cost: API-equivalent

Nautelle shows API-equivalent cost — what the recorded tokens would cost at public API prices — because agents often run on subscriptions where real spend per run is not observable. It is the same unit across runtimes and over time, and budgets use it.

• Tokens are split into buckets: input, output, cache read, cache write (5 min / 1 h) and reasoning.
• Prices come from a versioned price table, seeded from Langfuse's public model prices. A model is matched by a pattern and can have tiers.
• Cost is computed when a request is ingested, with the current version, and stored with that version.
• A model with no matching price is unpriced — shown as such, never as $0.

Editing prices

Admins edit prices in Admin › Prices. An edit never changes rows in place: it creates a new price version. To apply new prices to past usage, pick a date range and a version and recompute; a background job re-prices the requests and rebuilds the affected rollups.

Usage

Usage (/usage) answers "what did this cost". Pick a range, a time zone and optionally a project, and break the spend down by:

• project · model · runtime · issue · slot · run.

Numbers come from hourly rollups updated at ingest. Non-admins see only the projects they belong to. Usage also has a Token saver section with what Token Saver saved, and a Set a budget button.

The runner also listens for OpenTelemetry logs on 127.0.0.1:4318, so sessions with telemetry on report each request live instead of waiting for the transcript. nautelle-runner setup claude configures this (see Installing the Runner).

Budgets

A budget caps spend for a project or a user, per day, week or month, in a time zone you choose, with a limit in API-equivalent dollars.

1. Open Admin › Budgets, Project › Settings › Budget, or Usage › Set a budget.
2. Choose the scope, the period and the limit.
3. Choose the thresholds (default 50 %, 80 %, 100 %) and the action.

Action	At the limit
Alert	a notification at each threshold, once per period
Stop	the same alerts, and new spend is refused for that scope

With Stop, new skill runs, orchestrator start/next and scheduled runs are refused with 409 budget_exceeded, naming the budget and when it resets. User budgets also apply to the schedules that user owns. Work already running is never killed — stop means no new spend.

• Spend counts priced requests only; unpriced requests are shown next to the budget.
• Project spend is everything correlated to the project: workers, the orchestrator, skill runs, your own sessions in it.
• User spend is the runs that user started.
• An admin can override a stopped budget for the rest of the current period; every override and budget change is audited.
• Budgets reset automatically at the period boundary.

Admins manage project and user budgets; project operators can view their project's budget; a user sees their own.

See also

• Token Saver · Notifications and Telegram · Security and Access
• Cost model

Decisions: ADR-0003 · ADR-0009 · ADR-0021 · ADR-0050 · Spec: #12, #13, #28