opencode-token-monitor 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-02-08
+
+### Added
+- **Project-Aware Analytics**:
+  - Automatic session tagging with project IDs.
+  - New `scope` parameter for `token_stats` and `token_history` to filter trends and history by project.
+  - New `history_scope` parameter for `token_export` to filter range exports by project.
+  - Project ID inclusion in JSON, CSV, and Markdown exports.
+  - Backward-compatible history loading (legacy records included in global scope, excluded from project-specific scope).
+
+## [0.2.0] - 2026-02-08
+
+### Added
+- **Ecosystem Analytics**: 
+  - Token and cost attribution by Execution Agent and Initiator Agent.
+  - Agent×Model cross-breakdown table.
+  - Tool×Command attribution with safe command summaries.
+- **History & Trends**:
+  - Persistent session history storage.
+  - `token_history` tool for querying past usage.
+  - Trend analysis with ASCII bar charts for daily costs.
+  - Week-over-week change detection and cost spike alerts.
+- **Budgeting & Quotas**:
+  - Configurable daily, weekly, and monthly budget thresholds via `token-monitor.json`.
+  - Antigravity quota monitoring.
+  - Session-level and budget-level toast notifications.
+- **Enhanced `token_stats`**:
+  - `include_children` parameter for recursive session aggregation.
+  - `compact` mode for reducing output size.
+  - `agent_view`, `agent_sort`, and `agent_top_n` parameters for fine-grained control.
+- **Data Export**:
+  - `token_export` tool supporting JSON, CSV, and Markdown.
+- **Stability**:
+  - Automatic output truncation and Antigravity auto-degradation.
+
+### Changed
+- Refactored rendering logic into specialized `lib/renderer.ts`.
+- Improved model detection and pricing coverage (including Antigravity variants).
+- Updated `package.json` for NPM readiness.
+
+## [0.1.0] - 2026-02-01
+
+### Added
+- Initial release.
+- Basic `token_stats` tool with model breakdown.
+- Cost calculation with custom `pricing.json` support.
+- Core aggregation logic for input, output, reasoning, and cache tokens.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ainsley0917
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# opencode-token-monitor
+
+[![CI](https://github.com/Ainsley0917/opencode-token-monitor/actions/workflows/ci.yml/badge.svg)](https://github.com/Ainsley0917/opencode-token-monitor/actions/workflows/ci.yml)
+
+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
+
+### Manual Installation
+
+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`.
+
+### `token_stats`
+
+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.
+
+### `token_history`
+
+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).
+
+### `token_export`
+
+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.
+
+## 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
+
+### Pricing (`pricing.json`)
+
+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
+  }
+}
+```
+
+### Budgets (`token-monitor.json`)
+
+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](https://github.com/Ainsley0917)
+
+## License
+
+MIT

package/dist/lib/aggregation.d.ts

@@ -0,0 +1,20 @@
+import type { AssistantMessage, TokenStats, TokenStatsByModel, TokenStatsByAgent, TokenStatsByAgentModel, ToolAttributionResult, UserMessage } from "./types";
+export declare function aggregateTokens(messages: AssistantMessage[]): TokenStats;
+export declare function aggregateTokensByModel(messages: AssistantMessage[]): TokenStatsByModel;
+export declare function aggregateTokensByAgent(messages: AssistantMessage[]): TokenStatsByAgent;
+export declare function aggregateTokensByAgentModel(messages: AssistantMessage[]): TokenStatsByAgentModel;
+export declare function aggregateToolAttribution(parts: any[]): ToolAttributionResult;
+export declare function aggregateTokensByInitiator(messages: AssistantMessage[], userMessages: UserMessage[]): TokenStatsByAgent;
+export declare function topNAgents(stats: TokenStatsByAgent, costMap: Record<string, number>, n: number, sortBy: "cost" | "tokens"): {
+    rows: Array<{
+        agent: string;
+        stats: TokenStatsByAgent[string];
+        cost: number;
+    }>;
+    others?: {
+        agent: string;
+        stats: TokenStatsByAgent[string];
+        cost: number;
+        count: number;
+    };
+};

package/dist/lib/ascii-charts.d.ts

@@ -0,0 +1,7 @@
+export type ChartOptions = {
+    maxPoints?: number;
+    width?: number;
+    height?: number;
+};
+export declare function renderBarChart(values: number[], labels: string[], options?: ChartOptions): string;
+export declare function renderSparkline(values: number[], options?: ChartOptions): string;

package/dist/lib/budget.d.ts

@@ -0,0 +1,23 @@
+import type { SessionRecord } from "./types";
+import type { Severity } from "./quota";
+export type BudgetConfig = {
+    daily?: number;
+    weekly?: number;
+    monthly?: number;
+    thresholds?: {
+        warning?: number;
+        error?: number;
+    };
+};
+export type BudgetStatus = {
+    period: "daily" | "weekly" | "monthly";
+    limit: number;
+    spent: number;
+    remaining: number;
+    percentage: number;
+    severity: Severity;
+};
+export declare function loadBudgetConfig(basePath?: string): BudgetConfig;
+export declare function computeSpend(records: SessionRecord[], period: "daily" | "weekly" | "monthly"): number;
+export declare function getBudgetStatus(records: SessionRecord[], config: BudgetConfig): BudgetStatus[];
+export declare function formatBudgetSection(statuses: BudgetStatus[]): string;

package/dist/lib/cost-calculator.d.ts

@@ -0,0 +1,3 @@
+import type { TokenStatsByModel, PriceConfig, CostResult } from "./types";
+export declare function loadPricingConfig(configPath?: string): PriceConfig;
+export declare function calculateCost(stats: TokenStatsByModel, customPricing?: PriceConfig): CostResult;

package/dist/lib/data-prep.d.ts

@@ -0,0 +1,15 @@
+import type { Message, Part } from "@opencode-ai/sdk";
+import type { PreparedMessage, UserMessage } from "./types";
+type RawMessage = {
+    info: Message;
+    parts: Part[];
+};
+export declare function prepareMessages(rawMessages: RawMessage[]): {
+    assistant: PreparedMessage[];
+    user: UserMessage[];
+};
+export declare function prepareMessagesWithChildren(rootMessages: RawMessage[], childMessages: RawMessage[][]): {
+    assistant: PreparedMessage[];
+    user: UserMessage[];
+};
+export {};

package/dist/lib/export.d.ts

@@ -0,0 +1,15 @@
+import type { SessionRecord } from "./types";
+export type ExportFormat = "json" | "csv" | "markdown";
+export type ExportScope = "session" | "range";
+export interface ExportOptions {
+    format: ExportFormat;
+    scope: ExportScope;
+    sessionID?: string;
+    from?: Date;
+    to?: Date;
+    includeChildren?: boolean;
+}
+export declare function exportToJSON(records: SessionRecord[]): string;
+export declare function exportToCSV(records: SessionRecord[]): string;
+export declare function exportToMarkdown(records: SessionRecord[]): string;
+export declare function exportData(records: SessionRecord[], format: ExportFormat): string;

package/dist/lib/history.d.ts

@@ -0,0 +1,4 @@
+import type { SessionRecord } from "./types";
+export declare function getShardPath(date: Date, baseDir?: string): string;
+export declare function saveSessionRecord(record: SessionRecord, baseDir?: string): Promise<void>;
+export declare function loadHistoryForRange(from: Date, to: Date, baseDir?: string, projectID?: string): Promise<SessionRecord[]>;

package/dist/lib/notifications.d.ts

@@ -0,0 +1,14 @@
+import type { QuotaStatus, Severity } from "./quota";
+export type NotificationState = {
+    lastCost: number;
+    lastToastAt: number;
+    previousQuotaSeverities: Map<string, Severity>;
+};
+export declare function shouldShowToast(currentCost: number, quotaStatuses: QuotaStatus[], sessionID: string, nowOverride?: number): {
+    show: boolean;
+    message?: string;
+};
+export declare function updateState(sessionID: string, cost: number, quotaStatuses: QuotaStatus[]): void;
+export declare function resetState(sessionID: string): void;
+export declare function formatCostToast(cost: number, delta?: number): string;
+export declare function formatQuotaAlertToast(status: QuotaStatus): string;

package/dist/lib/optimization.d.ts

@@ -0,0 +1,12 @@
+import type { TokenStats, TokenStatsByModel, PriceConfig } from "./types";
+export type Suggestion = {
+    id: string;
+    message: string;
+    metric: string;
+    severity: "info" | "warning";
+};
+export declare function analyzeModelCosts(byModel: TokenStatsByModel, pricing: PriceConfig): Suggestion[];
+export declare function analyzeCacheEfficiency(stats: TokenStats): Suggestion[];
+export declare function analyzeReasoningUsage(byModel: TokenStatsByModel): Suggestion[];
+export declare function generateOptimizationSuggestions(stats: TokenStats, byModel: TokenStatsByModel, pricing: PriceConfig): Suggestion[];
+export declare function formatOptimizationSection(suggestions: Suggestion[]): string;

package/dist/lib/provider-stability.d.ts

@@ -0,0 +1,19 @@
+export type StabilityConfig = {
+    maxChars: number;
+    maxTableRows: number;
+    maxChartPoints: number;
+};
+export declare const DEFAULT_STABILITY_CONFIG: StabilityConfig;
+export type TruncatedResult = {
+    content: string;
+    truncated: boolean;
+    originalLength: number;
+    message?: string;
+};
+export declare function truncateOutput(content: string, config?: Partial<StabilityConfig>): TruncatedResult;
+export declare function limitTableRows<T>(rows: T[], config?: Partial<StabilityConfig>): {
+    rows: T[];
+    truncated: boolean;
+    totalCount: number;
+};
+export declare function getDebugInfo(sections: string[]): string;

package/dist/lib/quota.d.ts

@@ -0,0 +1,13 @@
+export type QuotaSource = "antigravity" | "codex";
+export type Severity = "info" | "warning" | "error";
+export type QuotaStatus = {
+    source: QuotaSource;
+    scope: string;
+    remainingFraction: number;
+    resetsAt?: string;
+    severity: Severity;
+};
+export declare function getSeverity(remainingFraction: number): Severity;
+export declare function loadAntigravityQuota(basePath?: string): QuotaStatus[];
+export declare function loadCodexQuota(basePath?: string): QuotaStatus[];
+export declare function loadAllQuota(): QuotaStatus[];

package/dist/lib/renderer.d.ts

@@ -0,0 +1,12 @@
+import type { topNAgents } from "./aggregation";
+import type { TokenStats, TokenStatsByAgentModel, TokenStatsByModel, ToolAttributionResult } from "./types";
+type TopNAgentsResult = ReturnType<typeof topNAgents>;
+export declare function renderHeader(sessionID: string, models: string[], isAntigravity: boolean, isCompact: boolean): string;
+export declare function renderTotals(totalStats: TokenStats): string;
+export declare function renderEstimatedCost(totalCost: number): string;
+export declare function renderModelTable(statsByModel: TokenStatsByModel, costByModel: Record<string, number>): string;
+export declare function renderAgentTable(title: string, rows: TopNAgentsResult, totalCost: number): string;
+export declare function renderAgentModelTable(statsByAgentModel: TokenStatsByAgentModel, totalCost: number): string;
+export declare function renderToolCommandTable(attribution: ToolAttributionResult, totalCost: number): string;
+export declare function renderWarnings(warnings: string[]): string;
+export {};

package/dist/lib/session-tree.d.ts

@@ -0,0 +1,22 @@
+import type { OpencodeClient } from "@opencode-ai/sdk";
+import type { AssistantMessage, TokenStats, TokenStatsByModel, PriceConfig } from "./types";
+export type SessionTreeOptions = {
+    maxDepth?: number;
+};
+export type SessionNode = {
+    sessionID: string;
+    messages: AssistantMessage[];
+    children: SessionNode[];
+};
+export type ChildSessionSummary = {
+    sessionID: string;
+    tokens: TokenStats;
+    cost: number;
+};
+export type SessionTreeStats = {
+    totals: TokenStats;
+    byModel: TokenStatsByModel;
+    childSummaries: ChildSessionSummary[];
+};
+export declare function listSessionTree(rootID: string, client: OpencodeClient, options?: SessionTreeOptions): Promise<SessionNode>;
+export declare function aggregateSessionTree(node: SessionNode, pricing: PriceConfig): SessionTreeStats;

package/dist/lib/trends.d.ts

@@ -0,0 +1,16 @@
+import type { SessionRecord } from "./types";
+export type DailyBucket = {
+    date: string;
+    cost: number;
+    tokens: number;
+    sessions: number;
+};
+export type TrendStats = {
+    buckets: DailyBucket[];
+    weekOverWeekDelta: number;
+    spikes: string[];
+};
+export declare function bucketByDay(records: SessionRecord[]): DailyBucket[];
+export declare function computeWeekOverWeek(buckets: DailyBucket[]): number;
+export declare function detectSpikes(buckets: DailyBucket[], threshold?: number): string[];
+export declare function analyzeTrends(records: SessionRecord[]): TrendStats;

package/dist/lib/types.d.ts

@@ -0,0 +1,107 @@
+import type { Part } from "@opencode-ai/sdk";
+export type AssistantMessage = {
+    id: string;
+    sessionID: string;
+    role: "assistant";
+    time: {
+        created: number;
+        completed?: number;
+    };
+    parentID: string;
+    modelID: string;
+    providerID: string;
+    mode: string;
+    path: {
+        cwd: string;
+        root: string;
+    };
+    summary?: boolean;
+    cost: number;
+    tokens: {
+        input: number;
+        output: number;
+        reasoning: number;
+        cache: {
+            read: number;
+            write: number;
+        };
+    };
+    finish?: string;
+};
+export type TokenStats = {
+    input: number;
+    output: number;
+    total: number;
+    reasoning: number;
+    cache: {
+        read: number;
+        write: number;
+    };
+};
+export type AgentTokenStats = TokenStats & {
+    messageCount: number;
+};
+export type AgentModelTokenStats = AgentTokenStats & {
+    agent: string;
+    model: string;
+};
+export type TokenStatsByModel = {
+    [key: string]: TokenStats;
+};
+export type TokenStatsByAgent = {
+    [key: string]: AgentTokenStats;
+};
+export type TokenStatsByAgentModel = {
+    [key: string]: AgentModelTokenStats;
+};
+export type ToolCallSummary = {
+    tool: string;
+    title: string;
+    callCount: number;
+    tokens: TokenStats;
+    cost: number;
+};
+export type ToolAttributionResult = {
+    byTool: Record<string, ToolCallSummary>;
+};
+export type UserMessage = {
+    id: string;
+    sessionID: string;
+    role: "user";
+    time: {
+        created: number;
+    };
+    agent: string;
+    model: {
+        providerID: string;
+        modelID: string;
+    };
+};
+export type PreparedMessage = {
+    info: AssistantMessage;
+    parts: Part[];
+};
+export type ModelPricing = {
+    input_per_million: number;
+    output_per_million: number;
+    cache_read_per_million?: number;
+    cache_write_per_million?: number;
+};
+export type PriceConfig = {
+    [modelKey: string]: ModelPricing;
+};
+export type CostResult = {
+    totalCost: number;
+    byModel: {
+        [modelKey: string]: number;
+    };
+    warnings: string[];
+};
+export type SessionRecord = {
+    sessionID: string;
+    projectID?: string;
+    timestamp: number;
+    totals: TokenStats;
+    byModel: TokenStatsByModel;
+    cost: number;
+};

package/dist/plugin/index.d.ts

@@ -0,0 +1,3 @@
+import { type Plugin, type PluginInput } from "@opencode-ai/plugin";
+export declare function getInFlightCount(): number;
+export default function (input: PluginInput): Promise<ReturnType<Plugin>>;