Options

--path <dir> — Directory to scan for .jsonl files (overrides agent auto-discovery)
--agent <name> — Filter by agent name (e.g., main, codegen)
--offset <time> — Only include sessions from the last N units (30m, 2h, 7d)
--provider <name> — Filter by model provider (anthropic, openai, ollama, etc.)
--details [session-id] — Show per-session details. Optionally pass a session ID to show just that session (searches across all agents for <id>.jsonl)
--table — Show details in compact table format (use with --details)
--format <type> — Output format: text (default), json, or discord
--json — Shorthand for --format json (backwards compat)
--help, -h — Show help message

Examples

# Last 24 hours summary
node scripts/session-cost.js --offset 24h

# Only the main agent
node scripts/session-cost.js --agent main

# Last 7 days, JSON output
node scripts/session-cost.js --offset 7d --json

# Discord-friendly format (for bots/chat)
node scripts/session-cost.js --format discord

# Discord format with filters
node scripts/session-cost.js --format discord --offset 24h --provider anthropic

# Filter by provider
node scripts/session-cost.js --provider anthropic

# All sessions in compact table format
node scripts/session-cost.js --details --table

# Custom path with details (overrides agent discovery, scans exact directory)
node scripts/session-cost.js --path /other/dir --details

# Single session detail (found automatically across agents)
node scripts/session-cost.js --details 9df7a399-8254-411b-a875-e7337df73d29

# Anthropic sessions from last 24h in table format
node scripts/session-cost.js --provider anthropic --offset 24h --details --table

Output Format

Text Summary (Default)

Results are grouped by agent, then by model within each agent. A grand total section shows per-agent subtotals and a combined total.

Found 52 .jsonl files across 2 agents, 52 matched

====================================================================================================
SUMMARY BY AGENT
====================================================================================================

Agent: main

  anthropic/claude-sonnet-4-5-20250929
  --------------------------------------------------------------------------------
    Sessions: 30
    Tokens:   1,234,567 (input: 900,000, output: 334,567)
    Cache:    read: 500,000 tokens, write: 200,000 tokens
    Cost:     $12.3456
      Input:       $5.4000
      Output:      $5.0185
      Cache read:  $1.5000  (included in total, discounted rate)
      Cache write: $0.4271  (included in total)

  anthropic/claude-opus-4-6
  --------------------------------------------------------------------------------
    Sessions: 5
    Tokens:   250,000 (input: 180,000, output: 70,000)
    ...

Agent: codegen

  anthropic/claude-sonnet-4-5-20250929
  --------------------------------------------------------------------------------
    Sessions: 17
    ...

====================================================================================================
GRAND TOTAL
====================================================================================================
  main                 — 35 sessions, $15.8200
  codegen              — 17 sessions, $8.5600

All agents (2)
--------------------------------------------------------------------------------
  Sessions: 52
  Tokens:   ...
  Cost:     $24.3800
  ...

When only a single agent is present, the grand total shows "All models (N)" instead.

Text Details (`--details`)

Shows per-session breakdown (session ID, agent, model, duration, timestamps, tokens, cache, cost) followed by the agent/model summary.

Table Format (`--details --table`)

Compact table view. When multiple agents are present, an Agent column is included.

SESSION DETAILS
============================================================================================================================================
Agent          Model                              Duration    Tokens        Cache               Cost        Session
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
main           anthropic/claude-sonnet-4.5        45 min      128.5K        15.2K / 8.1K        $0.3245     abc123def456
codegen        anthropic/claude-sonnet-4.5        12 min      45.3K         2.1K / 1.5K         $0.8921     xyz789abc012

With a single agent, the Agent column is omitted and the table matches the previous format.

JSON (`--format json`)

Results are nested by agent. Each agent contains its model summaries and an agent-level totals object. A top-level grandTotal aggregates across all agents.

{
  "agents": {
    "main": {
      "models": {
        "anthropic/claude-sonnet-4-5-20250929": {
          "sessions": 30,
          "tokens": { "input": 900000, "output": 334567, "total": 1234567 },
          "cache": { "read": 500000, "write": 200000 },
          "cost": { "total": 12.3456, "input": 5.4, "output": 5.0185, "cacheRead": 1.5, "cacheWrite": 0.4271 }
        }
      },
      "totals": {
        "sessions": 35,
        "tokens": { "input": 1080000, "output": 404567, "total": 1484567 },
        "cache": { "read": 600000, "write": 250000 },
        "cost": { "total": 15.82, ... }
      }
    },
    "codegen": {
      "models": { ... },
      "totals": { ... }
    }
  },
  "grandTotal": {
    "sessions": 52,
    "tokens": { "input": 1500000, "output": 600000, "total": 2100000 },
    "cache": { "read": 800000, "write": 350000 },
    "cost": { "total": 24.38, ... }
  }
}

Discord (`--format discord`)

Optimized for chat platforms (Discord, Slack, etc.) - concise, markdown-friendly, no tables:

💰 **Usage Summary**
(last 24h)

**Total Cost:** $24.38
**Total Tokens:** 2.1M
**Sessions:** 52

**By Agent:**
• main: $15.82 (35 sessions)
• codegen: $8.56 (17 sessions)

**By Provider:**
• anthropic: $22.50 (1.9M tokens)
• openai: $1.88 (200K tokens)

**Top Models:**
• anthropic/claude-sonnet-4.5: $18.20 (1.5M tokens)
• anthropic/claude-opus-4: $4.30 (400K tokens)
• openai/gpt-4o: $1.88 (200K tokens)

The "By Agent" section is shown only when multiple agents are present.

Output Fields

Agent — Agent name (derived from directory under ~/.openclaw/agents/)
Sessions — Number of session files analyzed
Tokens — Total, input, and output token counts
Cache — Cache read and write token counts
Cost — Total cost broken down by input, output, cache read, and cache write
Duration — Session duration in minutes (details mode)
Timestamps — First and last activity timestamps (details mode)

Notes

When --path is provided, it overrides agent auto-discovery and scans exactly that directory. The agent name is inferred from the path (e.g., .../agents/main/sessions → "main").
--agent and --provider filters can be combined (e.g., --agent main --provider anthropic).
Single session lookup (--details <id>) searches across all discovered agents to find the session file.

session-cost

Session Cost

Quick Start