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