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.

---

Storage

Usage data is written to ~/.openacp/usage.json with a debounce of 2 seconds to avoid hammering disk on rapid completions. The file is flushed synchronously on SIGTERM, SIGINT, and process exit to prevent data loss.

If the file is corrupt on startup, OpenACP saves a .bak backup and starts fresh.

---

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 retention is 90 days. Cleanup runs on startup and then every 24 hours for long-running daemon instances.

To configure retention:

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