`mayros budget`

Manage token budgets and track LLM cost across sessions. Supports session, daily, and monthly budget scopes with soft-stop warnings and optional hard enforcement.

Provided by the token-economy plugin.

Subcommands

`budget status`

Print the current budget summary table showing cost and limits for each scope (session, daily, monthly), total call count, and token breakdown.

Output fields:

Session / Daily / Monthly — used cost vs. limit, percentage, and status indicators ([WARNING], [EXCEEDED])
Calls — total LLM calls in the current session
Tokens — input, output, cache-read, and cache-write counts

`budget set <scope> <usd>`

Set or update a budget limit at runtime.

Arguments:

Argument	Description
`<scope>`	Budget scope: `session`, `daily`, or `monthly`
`<usd>`	Limit in USD (must be a positive number)

`budget reset [scope]`

Reset budget counters. If no scope is given, all counters are reset.

Arguments:

Argument	Description
`[scope]`	Scope to reset: `session`, `daily`, `monthly`, or `all` (default: `all`)

`budget models`

Show per-model cost breakdown for the current session. Lists each model used with its provider, call count, total tokens, and cost in USD.

`budget pricing`

Show the built-in model pricing catalog. Lists cost per 1M tokens (input, output, cache-read, cache-write) for common models from Anthropic, OpenAI, and Google.

`budget cache`

Show prompt cache statistics: entry count, hits, misses, hit rate percentage, and estimated savings in USD.

Only available when the prompt cache is enabled in the token-economy plugin configuration.

Examples

bash
# Check current budget status
mayros budget status

# Set a $5 daily limit
mayros budget set daily 5

# Set a $0.50 session limit
mayros budget set session 0.50

# View per-model cost breakdown
mayros budget models

# View pricing for supported models
mayros budget pricing

# Check prompt cache performance
mayros budget cache

# Reset all budget counters
mayros budget reset

# Reset only the session counter
mayros budget reset session

Configuration

Budget limits and enforcement can also be set in mayros.toml:

toml
[plugins.token-economy]
sessionLimitUsd = 2.0
dailyLimitUsd = 10.0
monthlyLimitUsd = 100.0
enforcement = "soft"       # "soft" (warnings) or "hard" (blocks tool calls)
gracePeriodCalls = 3       # tool calls allowed after hard limit exceeded

Token Economy — budgets and cost tracking overview
models — model configuration