opencode-token-monitor


OpenCode plugin for monitoring token usage, estimating costs, and tracking ecosystem analytics across AI coding sessions.

Features

- Real-time Monitoring: Track token usage (input/output/reasoning/cache) for all assistant messages.
- Ecosystem Analytics:
- Agent Breakdown: Detailed cost and token attribution by execution agent and initiator agent.
- Agent×Model Cross-breakdown: See which agents are using which models.
- Tool×Command Attribution: Identify high-cost tools and commands (safe summaries only).
- History & Trends:
- Persistent History: Automatically saves session records for long-term tracking.
- Trend Analysis: Daily cost trends, Week-over-week changes, and cost spike detection.
- Visual Charts: ASCII bar charts for cost trends directly in the terminal.
- Budgeting & Quotas:
- Budget Thresholds: Set daily, weekly, and monthly budget limits.
- Quota Integration: Monitor Antigravity quota remaining fractions.
- Live Notifications: Toast notifications for session costs and budget warnings.
- Advanced Export: Export data to JSON, CSV, or Markdown formats for external analysis.
- Stability Features: Automatic output truncation and "compact mode" for heavy sessions or Antigravity models.

Installation

$3

Add the plugin to your opencode.json configuration file. OpenCode will automatically download and load the plugin on startup.

Add "opencode-token-monitor@latest" to the plugin array:

``json
{
"plugin": [
"opencode-token-monitor@latest"
]
}
`

The opencode.json file can be located at:
- ~/.config/opencode/opencode.json (Global configuration)
- Project root directory (Project-level configuration)

Restart OpenCode after making this change.

$3

`bash
npm install -g opencode-token-monitor
`

Then copy the plugin to your OpenCode plugins directory:

`bash
cp $(npm root -g)/opencode-token-monitor/dist/plugin.js ~/.opencode/plugins/token-monitor.js
`

$3

1. Clone the repository:
`bash
git clone https://github.com/Ainsley0917/opencode-token-monitor.git
cd opencode-token-monitor
`
2. Install dependencies and build:
`bash
bun install
bun run build
`
3. Copy the plugin to your OpenCode plugins directory:
`bash
cp dist/plugin.js ~/.opencode/plugins/token-monitor.js
`

Usage

The plugin registers three tools: token_stats, token_history, and token_export.

$3

Show detailed token usage for the current or specified session.

Parameters:
- session_id (string, optional): Session ID to inspect. Defaults to current.
- include_children (boolean, optional): Include child sessions in aggregation.
- agent_view (string, optional): "execution", "initiator", or "both" (default).
- agent_sort (string, optional): Sort tables by "cost" (default) or "tokens".
- agent_top_n (number, optional): Show top N agents (default: 10). Use 0 to show all.
- trend_days (number, optional): Number of days for trend analysis (default: 7).
- scope (string, optional): Filter historical trends to "project" or "all" (default).
- compact (boolean, optional): Skip heavy tables (auto-enabled for Antigravity models).
- debug (boolean, optional): Include debug information.

$3

Query historical token usage over a date range.

Parameters:
- from (string, optional): Start date (ISO format, e.g., "2026-01-01").
- to (string, optional): End date (ISO format, e.g., "2026-02-07").
- scope (string, optional): Filter history to "project" or "all" (default).
- recalculate (boolean, optional): Recalculate historical costs using current pricing (default: false).

Note: If you pass from/to as YYYY-MM-DD, the to date is treated as inclusive (end-of-day).

$3

Export token data for external use.

Parameters:
- format (string, required): "json", "csv", or "markdown".
- scope (string, optional): "session" (default) or "range".
- session_id (string, optional): For session scope.
- from/to (string, optional): For range scope.
- history_scope (string, optional): Filter range data to "project" or "all" (default).
- file_path (string, optional): Save to a specific file.
- recalculate (boolean, optional): Range scope only. Recalculate historical costs using current pricing (default: false).

Project-Aware Analytics

The plugin automatically tracks usage on a per-project basis using the project ID provided by OpenCode.

- Automatic Tagging: Every session record is tagged with the current project ID.
- Scope Selection: Use scope: "project" (in token_stats/token_history) or history_scope: "project" (in token_export) to filter analytics to the current project.
- Backward Compatibility: History recorded before this feature was added is preserved. These "legacy" records are included when using scope: "all" (default) but are excluded when filtering by a specific project.
- No Manual Migration: The system handles mixed history gracefully without requiring any manual data updates.

Configuration

$3

Customize pricing in pricing.json (searched in current dir, ~/.opencode/, or ~/.config/opencode/):

`json
{
"anthropic/claude-sonnet-4": {
"input_per_million": 3.0,
"output_per_million": 15.0,
"cache_read_per_million": 0.30,
"cache_write_per_million": 3.75
}
}
`

$3

Set budget limits in token-monitor.json:

`json
{
"budget": {
"daily": 5.00,
"weekly": 25.00,
"monthly": 100.00
}
}
`

Development

`bash
bun test # Run 340+ tests
bun run typecheck # Verify types
bun run build # Bundle plugin
``

Created by @Ainsley0917

License

MIT