opencode

@telem/opencode-plugin adds telem_search and telem_fetch as agent tools in opencode, both backed by the same POST /v1/interactions endpoint the rest of Telem uses. The plugin also denies opencode’s built-in webfetch tool by default, so page reads route through telem_fetch and land in the same Telem trajectory as your searches.

Prerequisites

Node.js 22+
opencode with a plugin API of 1.17.0 or newer (the @opencode-ai/plugin package the plugin builds against).

Install

Get an API key. There’s no public dashboard yet — contact the Telem team for an API key. Some Telem deployments run open and don’t require one at all; see Authentication for details.
Run the install command. This one command does two things at once: it writes the plugin entry to opencode’s config file and materializes the package — there’s no separate “install” step.
Set your key. TELEM_API_KEY as a shell environment variable; skip this line if your deployment doesn’t need one.

opencode plugin @telem/opencode-plugin --global
export TELEM_API_KEY=...   # your key

The config file the install command writes to is opencode.jsonc — note the .jsonc extension, not .json, even though the command name and most of opencode’s docs write “json”.

Manual alternative

Add the package to the plugin array in opencode.jsonc yourself:

{
  "plugin": ["@telem/opencode-plugin"]
}

What you get

Two tools, both recorded into the same Telem trajectory:

telem_search — runs one or more search queries as a single Telem interaction and returns normalized, provider-attributed results.
telem_fetch — reads up to 5 whole web pages in one call, fetched as one interaction and rendered one section per URL.

Both tools are granted automatically to every agent, including opencode’s built-in explore and general subagents, so nothing extra is needed to make delegated agents able to search. Any permission you’ve already set explicitly still wins — the plugin only fills in what’s unset.

Configuration

The plugin defaults to the hosted Telem service at https://router.telem.ai. Options resolve per tool call — no opencode restart needed — with precedence, per key:

project .opencode/telem.json
~/.config/opencode/telem.json
TELEM_* environment variables

Credentials (TELEM_BASE_URL, TELEM_API_KEY) have no config-file key; they resolve from the environment only, but are still read fresh on every call.

File key	Env fallback	Meaning
`tier`	`TELEM_TIER`	Named result-field tier
`fields`	`TELEM_FIELDS` (comma-separated)	Explicit normalized fields; mutually exclusive with `tier`
`providersInclude`	`TELEM_PROVIDERS_INCLUDE` (comma-separated)	Replace the deployment’s provider set
`providersExclude`	`TELEM_PROVIDERS_EXCLUDE` (comma-separated)	Subtract providers from the selected set
`fullContent`	`TELEM_FULL_CONTENT` (`1` only)	Retrieve full content for the interaction; never rendered inline — use `telem_fetch` to read a page

Precedence: if both tier and fields resolve, the more specific source wins; on a tie, fields wins and the plugin logs a warning.

Example .opencode/telem.json:

{
  "tier": "extended",
  "providersExclude": ["slowprovider"]
}

Troubleshooting

`Telem search failed: HTTP 401` or `403`

TELEM_API_KEY is missing or invalid for a deployment that requires one.

`...answered without the V2 normalized contract (normalized_schema_version=...)`

The Telem deployment predates the V2 search contract. Upgrade the backend or point TELEM_BASE_URL at a V2 deployment — this is a deliberate hard stop rather than a silent empty result.

Config edits seem ignored

Check precedence: a project .opencode/telem.json shadows the home config and the environment. A malformed config file is silently ignored (with a one-time console warning) rather than failing the search — check opencode’s logs for a [telem] ignoring ... line.

Tools missing from the agent

The plugin only fills in unset permissions — an explicit deny you already configured for telem_search/telem_fetch (top-level or per-agent) always wins. Check opencode.jsonc’s permission block.