Skip to main content
The Periscope OpenCode plugin captures analytics events from your OpenCode coding sessions and sends them to Periscope. This gives your team visibility into AI coding tool usage — which models are used, how many tokens are consumed, what it costs, and how AI-assisted work connects to your git history.

​
What it captures

For each AI assistant message in your OpenCode session, the plugin records:
DataDescription
Model and providerWhich LLM model and provider was used (e.g., Claude Sonnet 4 via Anthropic)
Token usageInput tokens, output tokens, reasoning tokens, cache reads, and cache writes
CostDollar cost of the interaction
Git contextRepository URL, branch name, and current commit SHA
Commit detectionWhen a git commit or git merge happens during a session, the plugin captures the commit SHA
Session metadataSession ID, title, agent type, whether it is a sub-agent

​
Installation

1

Install the plugin

Install the Periscope analytics plugin from npm:
npm install @periscope/opencode-analytics
Or with Bun:
bun add @periscope/opencode-analytics
2

Add to your OpenCode config

Add the plugin to your OpenCode configuration file:
opencode.json
{
  "plugins": {
    "periscope-analytics": {
      "package": "@periscope/opencode-analytics"
    }
  }
}
3

Configure the endpoint

Create the analytics configuration file:
mkdir -p ~/.config/opencode
~/.config/opencode/analytics.json
{
  "endpoint": "https://ingest.periscope.sh"
}
4

Authenticate

The first time you use OpenCode with the plugin installed, it will prompt you to authenticate:
  1. A browser window opens for you to sign in (same account as the Periscope dashboard)
  2. After signing in, you are redirected back automatically
  3. The plugin stores your credentials and refreshes them as needed
You must be a member of a Periscope organization to authenticate.

​
How it works

The plugin runs in the background during your OpenCode session. It does not interfere with the assistant or slow down your workflow.
  • After each assistant message, the plugin extracts model, provider, token counts, cost, and git context, then sends an analytics event to Periscope asynchronously.
  • When a git commit or merge happens, the plugin detects the commit SHA and associates it with your session. This is how Periscope connects AI-assisted coding to specific commits — enabling traceability from “AI wrote this code” to “this commit was deployed.”
Events appear in the Analytics section of the Periscope dashboard, where you can view cost breakdowns, token usage over time, model distribution, and session history.

​
Privacy and security

  • The plugin does not send code content, file contents, or conversation messages to Periscope
  • Only metadata (model, tokens, cost, git refs) is captured
  • Authentication uses industry-standard OAuth 2.0
  • All data is transmitted over HTTPS

​
Troubleshooting

Ensure the plugin is correctly listed in your opencode.json. Check that port 14550 is not in use by another process.
Verify your ~/.config/opencode/analytics.json has the correct endpoint URL. Check that you have completed the authentication flow at least once. Events are sent asynchronously — there may be a short delay.
If you see authentication errors after a period of inactivity, restart OpenCode. The plugin will prompt you to sign in again.
Make sure you are running OpenCode from within a git repository. If the repo URL, branch, or SHA fields are empty in the dashboard, the plugin could not detect a git repository in your working directory.

Analytics dashboard

View your AI coding analytics in the Periscope dashboard.