OpenCode Plugin

The AgentLens OpenCode plugin captures everything that happens during an OpenCode coding session and sends it as structured traces to your AgentLens instance.

Installation

terminal

npm install opencode-agentlens

Configuration

Add the plugin to your opencode.json configuration file:

opencode.json

{
  "plugin": ["opencode-agentlens"]
}

Set the required environment variables:

terminal

export AGENTLENS_API_KEY="your-api-key"
export AGENTLENS_ENDPOINT="https://agentlens.vectry.tech"

You can also add these to a .env file in your project root.

What gets captured

Every OpenCode session becomes a trace with nested spans and events for each action taken during the session:

AGENT spanSessions

Each OpenCode session is captured as a top-level AGENT span. Includes session ID, start time, end time, and overall status.

LLM_CALL spanLLM calls

Every call to an LLM provider (Claude, GPT, etc.) is recorded with the full prompt, response, token counts, and cost.

TOOL_CALL spanTool calls

Tool invocations including file reads, writes, shell commands, search operations, and MCP tool calls. Captures input arguments and outputs.

TOOL_SELECTION decisionPermissions

Permission requests and grants are captured as decision points, showing what the agent asked to do and whether it was allowed.

CUSTOM spanFile edits

Every file creation, modification, and deletion is tracked with before/after content diffs.

CUSTOM eventGit diffs

Git operations (commits, diffs, branch changes) are captured as events with the full diff content.

Trace structure

A typical OpenCode session trace looks like this:

Trace: "opencode-session-abc123"
  |
  +-- Span: "session" (AGENT)
  |     +-- Span: "read-file: src/main.ts" (TOOL_CALL)
  |     +-- Span: "llm-call: claude-sonnet" (LLM_CALL)
  |     |     Decision: TOOL_SELECTION -> chose "edit-file" over "write-file"
  |     +-- Span: "edit-file: src/main.ts" (TOOL_CALL)
  |     +-- Span: "llm-call: claude-sonnet" (LLM_CALL)
  |     +-- Span: "bash: npm test" (TOOL_CALL)
  |     +-- Event: "git-diff" (CUSTOM)
  |     +-- Span: "bash: git commit" (TOOL_CALL)

Environment variables

Variable	Required	Description
AGENTLENS_API_KEY	Yes	API key for authentication
AGENTLENS_ENDPOINT	Yes	AgentLens server URL
AGENTLENS_ENABLED	No	Set to "false" to disable (default: "true")
AGENTLENS_SESSION_TAGS	No	Comma-separated tags to add to all session traces

Filtering sensitive data

By default, the plugin captures full file contents and command outputs. To filter sensitive data, set the AGENTLENS_REDACT_PATTERNS environment variable with a comma-separated list of regex patterns:

terminal

export AGENTLENS_REDACT_PATTERNS="password=.*,API_KEY=.*,Bearer .*"

Matched content is replaced with [REDACTED] before being sent to the server.