opencode-agentlens

opencode-agentlens

OpenCode plugin for AgentLens — trace your coding agent's decisions, tool calls, and sessions.

Requirements

• OpenCode >= 1.1.0
• An AgentLens account -- register at agentlens.vectry.tech/register
• An API key created in Settings > API Keys in the AgentLens dashboard

Install

npm install opencode-agentlens

Configuration

Environment Variables

Variable	Required	Default	Description
AGENTLENS_API_KEY	Yes	—	Your AgentLens API key.
AGENTLENS_ENDPOINT	No	AgentLens cloud	API endpoint URL.
AGENTLENS_ENABLED	No	true	Set to false to disable tracing.
AGENTLENS_CAPTURE_CONTENT	No	true	Capture message and tool output content.
AGENTLENS_MAX_OUTPUT_LENGTH	No	10000	Max characters to capture per output.
AGENTLENS_FLUSH_INTERVAL	No	5000	Flush interval in milliseconds.
AGENTLENS_BATCH_SIZE	No	100	Max items per batch before auto-flush.

OpenCode Setup

Add the plugin to your OpenCode configuration at ~/.config/opencode/opencode.json:

{
  "plugins": [
    {
      "name": "agentlens",
      "module": "opencode-agentlens"
    }
  ]
}

Set your API key (create one at Settings > API Keys in the AgentLens dashboard):

export AGENTLENS_API_KEY="your-api-key"

The plugin activates automatically when OpenCode starts. No code changes required.

Each OpenCode session counts as one trace (one session) for billing purposes. See the billing documentation for plan details.

What Gets Captured

The plugin hooks into OpenCode's event system and records:

• Sessions — Full session lifecycle from start to finish, including duration and metadata.
• Tool calls — Every tool invocation with input arguments and output results (e.g., file reads, shell commands, code edits).
• LLM calls — Chat messages sent to and received from the model, including token usage.
• Permission flows — When the agent requests permission and whether it was granted or denied.
• File edits — File paths and change summaries produced by the agent.

All data is sent to your AgentLens instance where you can inspect traces, replay sessions, and analyze agent behavior.

How It Works

The plugin registers handlers for OpenCode's event hooks:

Event	What is recorded
Session start/end	Trace lifecycle, session metadata
tool.execute.before	Tool name, input arguments
tool.execute.after	Tool output, duration, success/failure
chat.message	LLM responses and assistant messages
chat.params	Model parameters and prompt configuration
permission.ask	Permission requests and user decisions

Each OpenCode session maps to a single AgentLens trace. Tool calls and LLM interactions become spans within that trace.

Documentation

Full documentation: agentlens.vectry.tech/docs/opencode-plugin

License

MIT