# opencode-agentlens

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

[![npm version](https://img.shields.io/npm/v/opencode-agentlens.svg)](https://www.npmjs.com/package/opencode-agentlens)
[![license](https://img.shields.io/npm/l/opencode-agentlens.svg)](https://github.com/repi/agentlens/blob/main/LICENSE)

## Requirements

- OpenCode >= 1.1.0

## Install

```bash
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`:

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

Set your API key:

```bash
export AGENTLENS_API_KEY="your-api-key"
```

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

## 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](https://agentlens.vectry.tech/docs/opencode-plugin)

## License

MIT