Monitor and manage costs and budgets in a Paperclip company. Use this skill when the user asks about "budget", "costs", "spend", "token usage", "burn rate", "how much are agents spending", "set a budget", "increase budget", "agent is paused", "auto-paused", or anything related to financial tracking and budget enforcement in Paperclip. Also trigger when the user mentions cost optimization or wants to understand spending patterns.
Paperclip tracks every token spent by every agent and enforces budget limits to prevent runaway costs.
Each agent heartbeat reports cost events with:
Costs are aggregated per agent per month (UTC calendar month).
The overall monthly spend limit for all agents combined. Set via the web UI or API:
PATCH /api/companies/{companyId}
{ "budgetMonthlyCents": 100000 }
100000 cents = $1,000/month.
Individual agent spend limits. Set from the agent configuration page or API:
PATCH /api/agents/{agentId}
{ "budgetMonthlyCents": 5000 }
5000 cents = $50/month.
Paperclip enforces budgets automatically:
| Threshold | Action |
|---|---|
| 80% | Soft alert — agent is warned to focus on critical tasks only |
| 100% | Hard stop — agent is auto-paused, no more heartbeats |
An auto-paused agent can be resumed by:
pnpm paperclipai dashboard get
The dashboard includes current month spend vs budget for the company and each agent.
GET /api/companies/{companyId}/costs/summary # Company total
GET /api/companies/{companyId}/costs/by-agent # Per-agent breakdown
GET /api/companies/{companyId}/costs/by-project # Per-project breakdown
haiku for
formatting, opus for complex reasoning)