@toninho09/opencode-usage 1.0.0

package/AGENTS.md

@@ -0,0 +1,226 @@
+# OpenCode Plugin - Agent Guidelines
+
+## Development Commands
+
+### Type Checking
+```bash
+npx tsc --noEmit
+```
+Run TypeScript compiler in check-only mode. No files are emitted due to `noEmit: true` in tsconfig.json.
+
+**Note:** This project has no build, lint, or test scripts configured in package.json. Focus on type correctness and follow established code patterns.
+
+## Code Style Guidelines
+
+### Imports
+- Use ES6 module syntax with named imports preferred over default imports
+- Explicit type-only imports with `import type { }` for TypeScript types
+- Node.js built-in modules: Use `import * as fs from "fs"` or modern `import { } from "node:stream"` protocol
+- Import order: type imports first, then external dependencies, then internal modules
+- Group related imports together
+
+```typescript
+import type { Plugin } from "@opencode-ai/plugin"
+import * as fs from "fs"
+import * as path from "path"
+import * as os from "os"
+import { fetchWithTimeout, createProgressBar } from "./utils"
+import type { QueryResult } from "./types"
+```
+
+### Formatting
+- **Indentation:** 2 spaces (no tabs)
+- **Semicolons:** Required at end of statements
+- **Quotes:** Double quotes for strings (observed in codebase)
+- **Trailing commas:** Allowed in multi-line arrays/objects
+- **Line length:** Reasonable limits, prioritize readability over strict line length
+
+### TypeScript & Types
+- **Interfaces:** Use for object shapes, API responses, and contracts (`interface QueryResult`, `interface AuthConfig`)
+- **Type aliases:** Use for unions and when exporting existing types (`export type { CopilotUsageResponse }`)
+- **Annotations:** Explicit types required for function parameters and return types
+- **Type assertions:** Use `as Type` sparingly, prefer type guards and narrowing
+- **External types:** Use `any` for library types without definitions, add comments explaining usage
+- **Strict mode:** Enabled in tsconfig.json - no implicit any, strict null checks
+
+```typescript
+interface AuthProvider {
+  access?: string
+  refresh?: string
+  expires?: number
+  username?: string
+  type?: string
+}
+
+interface AuthConfig {
+  "github-copilot"?: AuthProvider
+  "anthropic"?: AuthProvider
+}
+
+export async function fetchCopilotUsage(authData: AuthProvider): Promise<CopilotUsageResponse>
+```
+
+### Naming Conventions
+- **Functions/Variables:** camelCase (`getCopilotUsageData`, `oauthToken`, `resetCountdown`)
+- **Interfaces/Types:** PascalCase (`QueryResult`, `CopilotUsageResponse`, `AuthProvider`)
+- **Constants:** SCREAMING_SNAKE_CASE (`GITHUB_API_BASE_URL`, `COPILOT_HEADERS`, `AUTH_CONFIG_PATH`)
+- **File names:** kebab-case (`copilot-handler.ts`, `notification.ts`, `usage-handler.ts`)
+- **Private functions:** No prefix, simply not exported from module
+- **Exported functions:** Export individually using `export function` or `export async function`
+
+### Error Handling
+- Always wrap network operations in try-catch blocks
+- Check `instanceof Error` before accessing error properties
+- Throw errors for critical failures (authentication, configuration issues)
+- Return `null` for non-critical failures (token exchange, optional file reads)
+- Provide descriptive error messages with context and status codes
+
+```typescript
+// Critical error - throw
+if (!oauthToken) {
+  throw new Error("No OAuth token found in auth data")
+}
+
+// Network error with detailed context
+try {
+  const response = await fetchWithTimeout(url, { headers })
+  if (!response.ok) {
+    const errorText = await response.text()
+    throw new Error(`GitHub API Error ${response.status}: ${errorText}`)
+  }
+  return await response.json()
+} catch (err) {
+  return {
+    success: false,
+    error: err instanceof Error ? err.message : String(err)
+  }
+}
+
+// Non-critical failure - return null
+function readAuthConfig(): AuthConfig | null {
+  try {
+    if (!fs.existsSync(AUTH_CONFIG_PATH)) {
+      return null
+    }
+    const content = fs.readFileSync(AUTH_CONFIG_PATH, "utf-8")
+    return JSON.parse(content) as AuthConfig
+  } catch {
+    return null
+  }
+}
+```
+
+### File Organization
+- **Entry point:** `index.ts` - plugin registration, command setup, exports `TestPlugin`
+- **Library code:** `lib/` directory for all implementation
+- **Types:** `lib/types.ts` - shared interfaces and type definitions
+- **Utilities:** `lib/utils.ts` - reusable helper functions (`fetchWithTimeout`, `createProgressBar`)
+- **Feature modules:** One concern per file (`copilot.ts`, `claude.ts`)
+- **Handlers:** `lib/*-handler.ts` - command handlers with output formatting
+- **Services:** `lib/notification.ts` - cross-cutting services like message sending
+
+### Function Design
+- **Small functions:** Single responsibility principle, aim for < 50 lines per function
+- **Internal vs exported:** Keep implementation details internal, export only public APIs
+- **Parameter objects:** Use interfaces for complex function parameters
+- **Pure functions:** Prefer pure functions for formatting and data transformation
+- **Async patterns:** Use explicit `async/await`, avoid callback patterns
+
+```typescript
+// Internal helper - not exported
+function formatQuotaLine(name: string, quota: QuotaDetail | undefined, width: number = 20): string {
+  if (!quota) return ""
+  if (quota.unlimited) {
+    return `${name.padEnd(14)} Unlimited`
+  }
+  const total = quota.entitlement
+  const used = total - quota.remaining
+  const percentRemaining = Math.round(quota.percent_remaining)
+  const progressBar = createProgressBar(percentRemaining, width)
+  return `${name.padEnd(14)} ${progressBar} ${percentRemaining}% (${used}/${total})`
+}
+
+// Public API - exported
+export async function getCopilotUsageData(): Promise<CopilotUsageResponse | null> {
+  const auth = readAuthConfig()
+  const copilotAuth = auth?.["github-copilot"]
+  if (!copilotAuth?.refresh) {
+    return null
+  }
+  return fetchCopilotUsage(copilotAuth)
+}
+```
+
+### API Integration
+- **Timeouts:** Always use `fetchWithTimeout` wrapper for network requests (default 10s timeout)
+- **Headers:** Build header objects with helper functions (`buildGitHubHeaders`, `buildClaudeHeaders`)
+- **Versioning:** Include API version in URLs (`/copilot_internal/v2/token`)
+- **User-Agent:** Set appropriate user agent for API requests
+- **Response handling:** Always check `response.ok` before parsing JSON
+- **Token management:** Support both access and refresh tokens with fallback logic
+
+### Configuration
+- **Auth file:** `~/.local/share/opencode/auth.json` (OpenCode standard location)
+- **Plugin config:** `opencode.json` for plugin registration
+- **Constants:** Define at module level for API URLs, timeouts, headers
+- **Environment:** No .env files - read from OpenCode's auth.json
+- **Path construction:** Use `path.join()` with `os.homedir()` for cross-platform compatibility
+
+```typescript
+const AUTH_CONFIG_PATH = path.join(os.homedir(), ".local", "share", "opencode", "auth.json")
+```
+
+### Output Formatting
+- **Message sending:** Use `sendIgnoredMessage` for non-interactive responses
+- **Progress bars:** `createProgressBar(percent, width)` for visual quota indicators
+- **Date/Time:** Use `Date` API for countdown calculations
+- **Localization:** Portuguese for user-facing command descriptions
+
+```typescript
+// Send formatted message to user
+await sendIgnoredMessage(client, sessionID, formattedOutput, params)
+
+// Create progress bar
+const progressBar = createProgressBar(percentRemaining, 20) // [##########----------] style
+```
+
+## Plugin Registration
+Commands registered in `index.ts`:
+- Plugin exports a function that returns hook configuration
+- Register commands in `config` hook via `opencodeConfig.command["name"]`
+- Set `template: ""` for slash commands without parameters
+- Set `description` in Portuguese for user-facing help
+- Handle command execution in `command.execute.before` hook
+- Throw `Error("__COMMAND_HANDLED__")` or similar to prevent default processing
+
+```typescript
+export const TestPlugin: Plugin = async ({ client }) => {
+  return {
+    config: async (opencodeConfig) => {
+      opencodeConfig.command ??= {}
+      opencodeConfig.command["usage"] = {
+        template: "",
+        description: "Mostra uso do Copilot e Claude Code",
+      }
+    },
+    "command.execute.before": async (input, output) => {
+      if (input.command === "usage") {
+        try {
+          await handleUsageCommand({ client, sessionID: input.sessionID, params: output })
+        } catch (err) {
+          console.error(err instanceof Error ? err.message : String(err))
+        }
+        throw new Error("__USAGE_COMMAND_HANDLED__")
+      }
+    },
+  }
+}
+```
+
+## Testing
+No test framework currently configured. When adding tests:
+- Add test runner to devDependencies (e.g., vitest, jest)
+- Add test scripts to package.json
+- Prefer unit tests for pure functions (`formatQuotaLine`, `createProgressBar`, `getResetCountdown`)
+- Integration tests for API calls (use mocked fetch responses)
+- Always ensure type checks pass: `npx tsc --noEmit`

package/README.md

@@ -0,0 +1,133 @@
+# OpenCode Usage Plugin
+
+Track your AI coding assistant usage in one place. This plugin shows quota information and usage statistics for GitHub Copilot, Claude Code, and Z.ai with a single command.
+
+## Table of Contents
+
+> **Note:** This plugin requires [OpenCode](https://opencode.ai) to be installed.
+
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [What You'll See](#what-youll-see)
+- [Features](#features)
+- [Configuration Reference](#configuration-reference)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+
+## Requirements
+
+Before installing this plugin, make sure you have:
+
+- [OpenCode installed](https://opencode.ai/docs)
+- Node.js installed (for local plugin installation)
+- API keys/tokens for at least one of the supported services:
+  - GitHub Copilot account
+  - Anthropic (Claude) API key
+  - Z.ai account
+
+## Quick Start
+
+### Step 1: Install OpenCode
+
+If you haven't already, install OpenCode using one of these methods:
+
+```bash
+# Quick install (recommended)
+curl -fsSL https://opencode.ai/install | bash
+
+# Or using npm
+npm install -g opencode-ai
+
+# Or using Homebrew (macOS/Linux)
+brew install anomalyco/tap/opencode
+```
+
+### Step 2: Install the Usage Plugin
+
+Choose one of the following installation methods:
+
+#### Option A: Install from Local Files
+
+Clone this repository to your project's plugins directory:
+
+```bash
+cd /path/to/your/project
+mkdir -p .opencode/plugins
+git clone https://github.com/toninho09/opencode-usage.git .opencode/plugins/opencode-usage
+cd .opencode/plugins/opencode-usage
+```
+
+**Tip:** For global installation (available in all projects), use:
+
+```bash
+mkdir -p ~/.config/opencode/plugins
+git clone https://github.com/toninho09/opencode-usage.git ~/.config/opencode/plugins/opencode-usage
+cd ~/.config/opencode/plugins/opencode-usage
+npm install
+```
+
+#### Option B: Install via npm (coming soon)
+
+```bash
+npm install -g opencode-usage
+```
+
+Then add to your `opencode.json` config file:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@toninho09/opencode-usage@latest"]
+}
+```
+
+### Step 3: Run OpenCode and Check Usage
+
+Navigate to your project and start OpenCode:
+
+```bash
+cd /path/to/your/project
+opencode
+```
+
+Now check your usage:
+
+```
+/usage
+```
+
+## What You'll See
+
+```
+╔════════════════════════════════════════╗
+║         GITHUB COPILOT                 ║
+╚════════════════════════════════════════╝
+Plan:            individual
+Premium:         [##                  ] 11% (33/300)
+Chat:            Unlimited
+Completions:     Unlimited
+Quota Resets:    18d 20h (9999-12-31 23:59 UTC-03:00)
+╔════════════════════════════════════════╗
+║       CLAUDE CODE                      ║
+╚════════════════════════════════════════╝
+5 Hour:          [################### ] 94%
+7 Day:           [#                   ] 7%
+5h Resets:       2h (9999-12-31 23:59 UTC-03:00)
+7d Resets:       6d 21h (9999-12-31 23:59 UTC-03:00)
+Extra Usage:     Disabled
+╔════════════════════════════════════════╗
+║       Z.AI CODING PLAN                 ║
+╚════════════════════════════════════════╝
+Account:         xxxxxxxx............ (Z.AI Coding Plan)
+Tokens:          [#                   ] 4%
+5h Resets:       3h (9999-12-31 23:59 UTC-03:00)
+MCP Searches:    [                    ] 0% (0/100)
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! Feel free to open an issue or pull request.

package/index.ts

@@ -0,0 +1,31 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { handleUsageCommand } from "./lib/usage-handler"
+
+export const TestPlugin: Plugin = async ({ client }) => {
+    return {
+        config: async (opencodeConfig) => {
+            opencodeConfig.command ??= {}
+            opencodeConfig.command["usage"] = {
+                template: "",
+                description: "Shows usage for Copilot, Claude Code and Z.ai",
+            }
+        },
+        "command.execute.before": async (input, output) => {
+            if (input.command === "usage") {
+                try {
+                    await handleUsageCommand({
+                        client,
+                        sessionID: input.sessionID,
+                        params: output,
+                    })
+                } catch (err) {
+                    console.error(err instanceof Error ? err.message : String(err))
+                }
+
+                throw new Error("__USAGE_COMMAND_HANDLED__")
+            }
+        },
+    }
+}
+
+export default TestPlugin

package/lib/providers/base.ts

@@ -0,0 +1,46 @@
+/**
+ * Common interface for all usage monitoring providers
+ */
+export interface UsageProvider {
+  /**
+   * Display name of provider (e.g., "GitHub Copilot")
+   */
+  readonly name: string;
+
+  /**
+   * Unique provider ID for internal use (e.g., "copilot")
+   */
+  readonly id: string;
+
+  /**
+   * Brief description of provider
+   */
+  readonly description: string;
+
+  /**
+   * Fetches usage data from provider API
+   * @returns ProviderMessage with formatted content or null if not configured
+   */
+  getUsageData(): Promise<ProviderMessage | null>;
+
+  /**
+   * Checks if provider is configured in auth file
+   * @returns true if provider is configured and ready to use
+   */
+  isConfigured(): boolean;
+}
+
+/**
+ * Message returned by provider with formatted usage data
+ */
+export interface ProviderMessage {
+  /**
+   * Formatted content for display to user
+   */
+  readonly content: string;
+
+  /**
+   * Error message if any problem occurred (optional)
+   */
+  readonly error?: string;
+}

package/lib/providers/claude/client.ts

@@ -0,0 +1,72 @@
+import { fetchWithTimeout } from "../../shared/utils";
+import { readAuthConfig, type AuthProvider } from "../../shared/auth";
+import type { ClaudeUsageResponse } from "./types";
+
+const ANTHROPIC_API_BASE_URL = "https://api.anthropic.com";
+
+export class ClaudeClient {
+  private readonly apiBaseUrl = ANTHROPIC_API_BASE_URL;
+
+  /**
+   * Builds headers for authentication with Claude API
+   */
+  private buildClaudeHeaders(token: string): Record<string, string> {
+    return {
+      "Accept": "application/json, text/plain, */*",
+      "Content-Type": "application/json",
+      "User-Agent": "claude-code/2.0.32",
+      "Authorization": `Bearer ${token}`,
+      "anthropic-beta": "oauth-2025-04-20",
+    };
+  }
+
+  /**
+   * Fetches usage data from Claude API
+   */
+  private async fetchClaudeUsage(authData: AuthProvider): Promise<ClaudeUsageResponse> {
+    const token = authData.access || authData.refresh;
+
+    if (!token) {
+      throw new Error("No token found in Anthropic auth data");
+    }
+
+    const url = `${this.apiBaseUrl}/api/oauth/usage`;
+    const response = await fetchWithTimeout(url, {
+      headers: this.buildClaudeHeaders(token),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Anthropic API Error ${response.status}: ${errorText}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Fetches Claude usage data
+   */
+  async fetchUsage(): Promise<ClaudeUsageResponse | null> {
+    const authConfig = readAuthConfig();
+
+    if (!authConfig) {
+      return null;
+    }
+
+    const authData = authConfig.anthropic;
+
+    if (!authData) {
+      return null;
+    }
+
+    return this.fetchClaudeUsage(authData);
+  }
+
+  /**
+   * Checks if Claude is configured
+   */
+  isConfigured(): boolean {
+    const authConfig = readAuthConfig();
+    return !!authConfig?.anthropic;
+  }
+}

package/lib/providers/claude/formatter.ts

@@ -0,0 +1,56 @@
+import { formatResetLine } from "../../shared/formatting";
+import { createUsedProgressBar } from "../../shared/utils";
+import type { ClaudeUsageResponse, QuotaPeriod } from "./types";
+
+export class ClaudeFormatter {
+  /**
+   * Formats a Claude quota line with progress bar
+   */
+  private formatQuotaLine(name: string, quota: QuotaPeriod | null): string {
+    if (!quota) {
+      return `${name.padEnd(16)} N/A`;
+    }
+
+    const percentUsed = Math.round(quota.utilization);
+    const progressBar = createUsedProgressBar(percentUsed, 20);
+
+    return `${name.padEnd(16)} ${progressBar} ${percentUsed}%`;
+  }
+
+  /**
+   * Formats Claude usage data for display
+   */
+  format(data: ClaudeUsageResponse): string {
+    const lines: string[] = [];
+
+    lines.push("╔════════════════════════════════════════╗");
+    lines.push("║       CLAUDE CODE                      ║");
+    lines.push("╚════════════════════════════════════════╝");
+
+    lines.push(this.formatQuotaLine("5 Hour:", data.five_hour));
+    lines.push(this.formatQuotaLine("7 Day:", data.seven_day));
+
+    if (data.five_hour) {
+      lines.push(formatResetLine("5h Resets:", data.five_hour.resets_at, 16));
+    }
+
+    if (data.seven_day) {
+      lines.push(formatResetLine("7d Resets:", data.seven_day.resets_at, 16));
+    }
+
+    const extraUsage = data.extra_usage;
+    if (extraUsage.is_enabled) {
+      const utilization =
+        extraUsage.utilization !== null ? `${Math.round(extraUsage.utilization)}%` : "N/A";
+      const credits =
+        extraUsage.used_credits !== null && extraUsage.monthly_limit !== null
+          ? `${extraUsage.used_credits}/${extraUsage.monthly_limit}`
+          : "N/A";
+      lines.push(`Extra Usage:     Enabled - ${utilization} (${credits})`);
+    } else {
+      lines.push("Extra Usage:     Disabled");
+    }
+
+    return lines.join("\n");
+  }
+}

package/lib/providers/claude/index.ts

@@ -0,0 +1,36 @@
+import type { UsageProvider, ProviderMessage } from "../base";
+import { ClaudeClient } from "./client";
+import { ClaudeFormatter } from "./formatter";
+
+const client = new ClaudeClient();
+const formatter = new ClaudeFormatter();
+
+export const claudeProvider: UsageProvider = {
+  name: "Claude Code",
+  id: "claude",
+  description: "Monitoramento de uso do Claude Code",
+
+  async getUsageData(): Promise<ProviderMessage | null> {
+    try {
+      const data = await client.fetchUsage();
+      if (!data) {
+        return null;
+      }
+
+      return {
+        content: formatter.format(data),
+      };
+    } catch (error) {
+      return {
+        content: "",
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  },
+
+  isConfigured(): boolean {
+    return client.isConfigured();
+  },
+};
+
+export default claudeProvider;

package/lib/providers/claude/types.ts

@@ -0,0 +1,22 @@
+export interface QuotaPeriod {
+  utilization: number;
+  resets_at: string;
+}
+
+export interface ExtraUsage {
+  is_enabled: boolean;
+  monthly_limit: number | null;
+  used_credits: number | null;
+  utilization: number | null;
+}
+
+export interface ClaudeUsageResponse {
+  five_hour: QuotaPeriod | null;
+  seven_day: QuotaPeriod | null;
+  seven_day_oauth_apps: QuotaPeriod | null;
+  seven_day_opus: QuotaPeriod | null;
+  seven_day_sonnet: QuotaPeriod | null;
+  seven_day_cowork: QuotaPeriod | null;
+  iguana_necktie: unknown | null;
+  extra_usage: ExtraUsage;
+}