OpenCode Token Usage Tools

A simple, fast tool to check OpenCode session token usage

Features

• Fast token usage summary for OpenCode sessions (no dependencies)
• Session list view with title, model/provider, message count, totals
• Latest session view by default
• Filters by time range, plus --top and --recent
• Sort by time, tokens, provider, or model
• CSV export for spreadsheets or reporting
• One-command install + tok shortcut

Quick Start

Install

# One-line installation
curl -fsSL https://raw.githubusercontent.com/xyizhan/opencode-token-tools/main/install.sh | bash

# Or manually
git clone https://github.com/xyizhan/opencode-token-tools.git
cd opencode-token-tools
./install.sh

Usage

# Show latest session (default)
opencode-token
tok

# Show all sessions (summary)
opencode-token --all
tok --all

# Show specific session
opencode-token --session ses_xxx

# Export to CSV
opencode-token --all --export tokens.csv

# List all session IDs
opencode-token --list-sessions

Examples

# Check version
opencode-token --version

# Show latest session
opencode-token --latest

# Show with details
opencode-token --latest --detailed

# Sort sessions by tokens
opencode-token --all --sort tokens

# Last 7 days
opencode-token --all --since 2026-01-20

# Time range with top N
opencode-token --all --since 2026-01-01 --until 2026-01-31 --top 10

# Top N by tokens (default)
opencode-token --top 5

# Most recent N sessions
opencode-token --recent 5

Output

The table view displays:

• Session ID
• Session Title
• Provider and Model
• Number of messages
• Token usage (input, output, reasoning, cache)
• Totals (with and without cache)
• Updated time (from session metadata when available)

Single session view additionally shows a detailed breakdown and cache efficiency when using --detailed.

Options

--all, -a            Show all sessions summary
--session, -s ID     Show a specific session
--latest, -l         Show latest session
--list-sessions      List all session IDs and titles (newest first)
--detailed, -d       Show detailed breakdown (single session only)
--sort {provider,model,tokens,time}  Sort sessions when using --all
--since TIME         Filter sessions updated since TIME (YYYY-MM-DD or YYYY-MM-DD HH:MM)
--until TIME         Filter sessions updated until TIME (YYYY-MM-DD or YYYY-MM-DD HH:MM)
--top N              Show top N sessions by tokens
--recent N           Show N most recent sessions
--export FILE        Export to CSV file (defaults to --all if no session specified)
--version, -v        Show version

How It Works

• Token usage is read from OpenCode message files under ~/.local/share/opencode/storage/message.
• Session titles and update times are read from OpenCode session metadata under ~/.local/share/opencode/storage/session.
• --latest uses the latest updated session time (not lexicographic ID).
• --top defaults to sorting by token total (without cache) unless you set --sort.
• --recent shows the most recently updated sessions.

CSV Export

CSV export includes the following columns:

session_id,title,provider,model,messages,input,output,reasoning,cache_read,cache_write,total_without_cache,total_with_cache,updated_at,directory,project_id

Configuration

• Default storage path: ~/.local/share/opencode
• Override storage path with env var: OPENCODE_STORAGE=/path/to/opencode

Privacy

Exported CSV includes session titles and local project directory paths (when available). Review before sharing.

License

MIT License - see LICENSE file for details.