OpenACP/docs/gitbook/features/usage-and-budget.md
0xmrpeter add905a40c docs: clean up and simplify gitbook documentation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-01 22:28:37 +07:00

2.3 KiB

Usage & Budget

Token tracking

Every time an agent completes a prompt, OpenACP records a usage entry containing the session ID, timestamp, number of tokens consumed, and cost in USD (if the agent reports it). These records are stored in ~/.openacp/usage.json.

You can query usage summaries for different time periods:

Period Covers
today From midnight local time to now
week Rolling 7-day window
month Current calendar month (1st of month to now)
all All records within the retention window

Each summary includes total tokens, total cost, number of distinct sessions, and the record count.


Monthly budget

Set a spending limit in ~/.openacp/config.json:

{
  "usage": {
    "monthlyBudget": 20.00,
    "warningThreshold": 0.8
  }
}
Field Default Description
monthlyBudget none Monthly spending limit in USD. Leave unset to disable budget checking.
warningThreshold 0.8 Fraction of the budget at which to send a warning (0.8 = 80%)

Warning and exceeded notifications

When a session completes and usage crosses a threshold, OpenACP sends a notification to your connected platform (Telegram or Discord):

  • Warning — sent once when monthly cost reaches warningThreshold * monthlyBudget. Shows a progress bar and current percentage.
  • Exceeded — sent once when monthly cost reaches or exceeds monthlyBudget. Includes a note that sessions are not blocked — this is a soft limit only.

Notifications are de-duplicated: the same status level is not sent again within the same calendar month. At the start of a new month the counter resets automatically.

Example notification:

⚠️ Budget Warning
Monthly usage: $16.32 / $20.00 (82%)
▓▓▓▓▓▓▓▓░░ 82%

Retention

Usage records older than the configured retention period are deleted automatically. The default is 90 days.

To configure retention:

{
  "usage": {
    "retentionDays": 90
  }
}

Technical details

Usage data is stored in ~/.openacp/usage.json. Writes are batched to avoid excessive disk I/O. The file is saved on process exit to prevent data loss. If the file is corrupt on startup, OpenACP saves a backup and starts fresh.