OpenCode

Fastest install: the one-line curl — it detects the agent frameworks you already have and installs Telem into as many of them as you select in one pass. The steps below are the manual path.

@telemai/opencode-plugin adds telem_search and telem_fetch as agent tools in OpenCode. It also denies OpenCode’s built-in webfetch tool by default, so page reads route through telem_fetch.

What it looks like

A real opencode run, replayed — the model reaches for telem_search on its own, sends both angles as one interaction, then reads the winning pages with telem_fetch before it answers.

~/project — opencode

Three things to notice:

• No prompting for it. The plugin registers the tools and tells the model to prefer them; nothing in the prompt above names telem_search.
• One interaction, several queries. Both queries went out in a single telem_search call, ran concurrently, and came back provider-attributed in one envelope — not two round trips.
• It is all in the console. That run shows up in the Telem console as a session trajectory: every query, the providers that answered, and the pages the fetch pulled.

Interactive OpenCode is the same thing with the TUI around it — opencode, then ask.

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 or upgrade with:

  npm i -g opencode-ai

Install

1. Get an API key in the Telem console, under API keys in your project — see Authentication.

2. Run the install command. It writes the plugin entry to OpenCode’s config and materializes the package in one step.

3. Set your key. TELEM_API_KEY as a shell environment variable; skip this line if your deployment doesn’t need one.

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

The config file it writes to is opencode.jsonc — .jsonc, not .json, despite what the command name and most of OpenCode’s docs say.

Manual alternative

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

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

What you get

Two tools:

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

The plugin tells the model to prefer telem_search over an overlapping public-web search tool unless you ask otherwise, Telem is unavailable, or the task needs a capability Telem does not expose. That is soft preference, not a tool block: the only hard enforcement is the existing deny for OpenCode’s built-in webfetch (set TELEM_ALLOW_BUILTIN_WEBFETCH=1 to opt out).

Both tools are granted automatically to every agent, including OpenCode’s built-in explore and general subagents. Any permission you set explicitly still wins — the plugin only fills in what’s unset.

Configuration

One file, every harness. Telem options live in .telem/telem.json — a project one you can commit so the whole team inherits it, and a user one at ~/.telem/telem.json.

{
  "tier": "extended",
  "providersInclude": ["exa", "brave"]
}

The three keys most people reach for:

File key	Env fallback	Meaning
tier	TELEM_TIER	Named result-field tier: minimalist, default, extended, or max
fields	TELEM_FIELDS (comma-separated)	Explicit normalized fields; mutually exclusive with tier
providersInclude	TELEM_PROVIDERS_INCLUDE (comma-separated)	Replace the deployment’s provider set

Full parameter reference → — every key, its env fallback and how the levels compose.

OpenCode reads its own plugin options object first, then the project file, the user file, and TELEM_*. Resolution is per key and per call, so an edit to either file takes effect on the next search with no OpenCode restart.

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.

The OpenCode options object

OpenCode’s own plugin entry takes an options object, which the plugin honors as an explicit override above every file:

{
  "plugin": [["@telemai/opencode-plugin", { "tier": "max" }]]
}

It is read once, when OpenCode loads the plugin, so an edit here needs a restart. Prefer .telem/telem.json unless you want a machine-local override.

Troubleshooting

Telem search failed: HTTP 401 or 403

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

...answered without the normalized search envelope (normalized_schema_version=...)

The Telem deployment predates the normalized search response the plugin reads. Upgrade the backend, or point TELEM_BASE_URL at a current deployment — this is a deliberate hard stop rather than a silent empty result.

Config edits seem ignored

Precedence is per key: each level shadows the ones below it only for the keys it sets. The usual culprits are a project .telem/telem.json, which sits above ~/.telem/telem.json, and the options object in opencode.jsonc, which shadows everything and only reloads when OpenCode does. A malformed config file is 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.