@digitalygo/opencode-usage-logger

A plugin for logging OpenCode AI usage events to an external API.

Installation

npm install @digitalygo/opencode-usage-logger
# or
yarn add @digitalygo/opencode-usage-logger
# or
bun add @digitalygo/opencode-usage-logger

Usage

The plugin reads configuration from three sources, in order of precedence:

1. Plugin options in opencode.json (highest priority)
2. Dedicated JSON file (.opencode/usage-logging.json by default, or a custom path via configFile)
3. Environment variables (lowest priority)

Configuration sources

Option 1: Plugin options (recommended for simple setups)

Add configuration directly in opencode.json or opencode.jsonc:

{
  "plugin": [
    ["@digitalygo/opencode-usage-logger", {
      "usageLogApiBase": "https://your-api-endpoint.com",
      "usageLogApiKey": "{env:USAGE_LOG_API_KEY}"
    }]
  ]
}

Option 2: Dedicated JSON file

Create .opencode/usage-logging.json (gitignored by default):

{
  "usageLogApiBase": "https://your-api-endpoint.com",
  "usageLogApiKey": "your-api-key-here"
}

See .opencode/usage-logging.example.json for a template. This file is gitignored and should contain real secrets.

To use a custom file path, set the configFile option:

{
  "plugin": [
    ["@digitalygo/opencode-usage-logger", {
      "configFile": "./config/my-usage-config.json"
    }]
  ]
}

Or use the default .opencode/usage-logging.json:

{
  "plugin": [
    ["@digitalygo/opencode-usage-logger", {
      "configFile": ".opencode/usage-logging.json"
    }]
  ]
}

The configFile contains both usageLogApiBase and usageLogApiKey, so no need to specify them separately.

Option 3: Environment variables

Set these in your shell or .opencode/.env:

# Required: Base URL for the usage logging API
USAGE_LOG_API_BASE=https://your-api-endpoint.com

# Required: API key for authentication
USAGE_LOG_API_KEY=your-api-key-here

Plugin options reference

| Option | Type | Description | |--------|------|-------------| | usageLogApiBase | string | Base URL for the usage logging API. Can be a plain string or {env:VAR_NAME}. | | usageLogApiKey | string | API key for authentication. Can be a plain string or {env:VAR_NAME}. | | configFile | string | Path to a JSON config file containing usageLogApiBase and usageLogApiKey. Default: .opencode/usage-logging.json |

What it logs

This plugin captures usage events for assistant messages including:

• Event type: message.updated, message.created, usage.updated
• Model information: provider ID, model ID
• Token usage: input, output, reasoning tokens
• Cost information: total usage cost
• Metadata: project code (from git remote), logged user, timestamp

Local logging

Failed API attempts are logged locally to .opencode/logs/usage-api.log for debugging purposes.

License

MIT