usage

Documentation

Overview

Package usage estimates token spend locally from the per-message usage blocks the agent CLIs already write — no credentials, no provider API, no network. Everything it reports is an estimate from transcripts on this machine: it cannot see provider-side limits, spend on other machines, or anything the transcripts do not record. Rolling 5-hour and 7-day windows, a 30-minute burn rate, a per-session attribution table, and per-project cache-hit stats, all derived read-only.

Index

• Constants
• func JSON(rep Report) ([]byte, error)
• type ModelUse
• type Options
• type ProjectCache
• type Report
  • func Collect(opt Options) Report
• type SessionUse

Constants

const SchemaVersion = 1

SchemaVersion is the --json contract version for `agentdash usage`. Additive only, independent of the other commands' versions.

Functions

func JSON

func JSON(rep Report) ([]byte, error)

JSON renders a Report as the schema_version 1 usage document. The header note is part of the contract: everything here is a local estimate.

Types

type ModelUse

type ModelUse struct {
	Model string `json:"model"`
	In5h  int64  `json:"in_5h"`
	Out5h int64  `json:"out_5h"`
	In7d  int64  `json:"in_7d"`
	Out7d int64  `json:"out_7d"`
}

ModelUse is one model's windowed totals (in includes cache tokens, matching the board's accounting; out is output tokens).

type Options

type Options struct {
	Home  string
	Now   int64
	Limit int64 // optional 5h-window token cap for the projection; 0 = unknown
	TopN  int   // attribution rows (0 -> 10)
	// Labels maps a transcript path to a user-set task label; when present it
	// overrides the transcript-derived attribution title, so a session renamed
	// on the board reads the same in the usage breakdown.
	Labels map[string]string
}

Options configure a report.

type ProjectCache

type ProjectCache struct {
	Project       string  `json:"project"`
	CacheRead     int64   `json:"cache_read"`
	CacheCreation int64   `json:"cache_creation"`
	HitRatio      float64 `json:"hit_ratio"`
	RecentRatio   float64 `json:"recent_ratio"`
	PriorRatio    float64 `json:"prior_ratio"`
	Dropped       bool    `json:"dropped"`
}

ProjectCache is one project's cache-hit accounting over 7 days, with a flag when the hit ratio dropped sharply in the last day.

type Report

type Report struct {
	Now          int64          `json:"-"`
	Limit        int64          `json:"limit"`
	Models       []ModelUse     `json:"models"`
	BurnPerMin   float64        `json:"burn_per_min"`
	Total5h      int64          `json:"total_5h"`
	Total7d      int64          `json:"total_7d"`
	ProjFillSecs int64          `json:"proj_fill_secs"` // >0 only when Limit>0 and burning
	Sessions     []SessionUse   `json:"sessions"`
	Projects     []ProjectCache `json:"projects"`
}

Report is a completed usage estimate.

func Collect

func Collect(opt Options) Report

Collect scans both transcript stores and builds the report.

type SessionUse

type SessionUse struct {
	Title      string  `json:"title"`
	Agent      string  `json:"agent"`
	Model      string  `json:"model"`
	In         int64   `json:"in"`
	Out        int64   `json:"out"`
	SharePct   float64 `json:"share_pct"`
	IsSubagent bool    `json:"is_subagent"`
}

SessionUse is one session's spend inside the 5h window, for attribution.