Pi

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/pi-telem adds telem_search and telem_fetch as agent tools in the Pi coding agent

Prerequisites

Node.js 22+
Pi installed and working — install or upgrade with:
Terminal window
```
npm i -g --ignore-scripts @earendil-works/pi-coding-agent
```

Install

Get an API key in the Telem console, under API keys in your project — see Authentication.
Run the install command. It installs the extension and the companion skill together.
Set your key. TELEM_API_KEY as a shell environment variable; skip this line if your deployment doesn’t need one.
Reload if Pi was already running. Type /reload inside an open Pi session; a fresh pi start doesn’t need this.

pi install npm:@telemai/pi-telem
export TELEM_API_KEY=...   # your key

What you get

Two pieces, installed together:

The extension (telem_search, telem_fetch) — the same two tools as OpenCode and OpenClaw.
A skill (/skill:telem) — teaches the agent when to reach for the tools, and bundles standalone, zero-dependency CLI scripts (scripts/search.mjs, scripts/fetch.mjs) that work even in a harness where the extension tools aren’t available. When the extension tools are present, the skill defers to them.

The extension 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 only — the Pi package installs no call-blocking hook for other search or fetch tools.

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.

Pi reads the project file, then the user file, then TELEM_*, per key and per call — edit a file and the next search picks it up, no Pi restart.

The project file is honored only in a trusted project. An untrusted checkout steers no .telem/telem.json; the user file and the environment are unaffected.

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 skill’s CLI scripts

scripts/search.mjs reads the same three levels, fresh on every invocation, with two differences that follow from a CLI having no host: the project is whatever directory you run the script in, and there is no trust gate. Config notices print to stderr, so piping stdout keeps the results clean.

Troubleshooting

`pi install` rejects the package name

The npm: prefix is required. pi install @telemai/pi-telem — the bare package name, without the prefix — is rejected, because Pi reads a bare name as a local path rather than an npm source. Use pi install npm:@telemai/pi-telem.

Agent uses `bash curl` instead of the tools

The package isn’t loaded. Run pi list to confirm @telemai/pi-telem is installed, /reload after installing into a session that was already open, and confirm the project is trusted if you’re relying on a project-local install.

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

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

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

The Telem deployment predates the normalized search response the package 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

The usual culprit is a project .telem/telem.json, which sits above ~/.telem/telem.json, or an untrusted project, in which case the project file does not apply at all. See precedence. A malformed config file is silently ignored (with a one-time warning) rather than failing the search.

Both tier and fields warning

You’ve configured both in the same or across precedence layers. Keep one, or accept the documented tie-break — see precedence.

Pi