Token Usage & Cost Tracking

⚠️ Experimental — Squad is alpha software. APIs, commands, and behavior may change between releases.

Squad can track token usage and estimated cost for each agent spawn, roll that data up by session, and expose it through orchestration logs, terminal summaries, and telemetry backends.

Overview

• Squad tracks token usage (input/output tokens) and estimated cost per agent spawn
• Usage data is recorded in orchestration logs and available via squad cost CLI
• Optional budget limits can be configured per agent or per session

How It Works

• The CostTracker class (packages/squad-sdk/src/runtime/cost-tracker.ts) accumulates token data
• Each orchestration log entry includes a Token usage row
• OTel metrics (squad.tokens.input, squad.tokens.output, squad.tokens.cost) are emitted when telemetry is enabled

The orchestration log template stores usage in a markdown table row like this:

| **Token usage** | 12,450 in / 3,200 out — $0.0234 |

Viewing Costs

squad cost                 # current session costs
squad cost --all           # all historical costs
squad cost --agent fenster # costs for specific agent

Example output:

=== Squad Cost Summary ===
Total input tokens:  12,450
Total output tokens: 3,200
Estimated cost:      $0.0234

--- By Agent ---
  fenster: 12,450in / 3,200out ($0.0234) [1 turns, model: claude-sonnet-4.5]

--- By Session ---
  session-abc123: 12,450in / 3,200out ($0.0234) [1 turns]

Budget Configuration

import { defineSquad, defineAgent, defineBudget } from '@bradygaster/squad-sdk';

export default defineSquad({
  defaults: {
    budget: defineBudget({
      perAgentSpawn: 50000,
      perSession: 500000,
      warnAt: 0.8,
    }),
  },
  agents: [
    defineAgent({
      name: 'fenster',
      role: 'Core Dev',
      budget: defineBudget({ perAgentSpawn: 100000 }),
    }),
  ],
});

• perAgentSpawn limits an individual agent invocation
• perSession limits the total budget for the coordinator session
• warnAt emits warnings when usage reaches a fraction of the configured limit

OTel Integration

• Token metrics are exported as OpenTelemetry counters when telemetry is enabled
• Compatible with Aspire dashboard, Grafana, and any OTel-compatible backend
• Metrics: squad.tokens.input, squad.tokens.output, squad.tokens.cost