pi-telem — Telem web search & fetch for the Pi coding agent

A Pi package that lets the Pi coding agent route web search and web page fetching through a Telem deployment. The Pi counterpart of the Telem OpenCode plugin (@telemai/opencode-plugin) and the Telem OpenClaw plugin (@telemai/openclaw-plugin), speaking the same normalized search envelope and session observability protocol.

What's inside

Piece	Path	What it does
Extension	extensions/telem/index.ts	Registers the telem_search and telem_fetch tools with the LLM. Each call sends one Search request carrying the conversation history and trajectory v5 identity metadata, gates on the V2 normalized envelope, and renders results with the shared telem-render region.
Skill	skills/telem/	Agent-Skills-standard skill: tells the model when to search/fetch and ships zero-dependency CLI scripts (scripts/search.mjs, scripts/fetch.mjs) as a fallback for harnesses without the extension. When the extension tools are present the skill defers to them.

Install

The guided installer is the quickest path — it configures the plugin and captures your API key from app.telem.ai in one pass:

npm create @telemai

Pick Pi when it asks, or skip the interview entirely:

npm create @telemai -- --client pi

By hand

Set the endpoint and your key explicitly — npm create @telemai writes both for you:

pi install npm:@telemai/pi-telem
export TELEM_BASE_URL=https://router.telem.ai
export TELEM_API_KEY=...              # from https://app.telem.ai

The npm: prefix is required — pi install @telemai/pi-telem (bare name) is rejected as a local path.

TELEM_BASE_URL defaults to the hosted Telem service at https://router.telem.ai. Set it only if Telem gave you a different endpoint.

Installing from a local checkout, for development: see Development.

Configuration

Telem options live in .telem/telem.json — one project file and one user file that every Telem harness reads, not a config per host. Options resolve per tool call (no Pi restart needed) and per key, top wins:

1. project <project>/.telem/telem.json — trusted projects only
2. project .pi/telem.json — deprecated, trusted projects only
3. ~/.config/pi/telem.json — deprecated
4. user ~/.telem/telem.json (relocatable with TELEM_CONFIG_DIR)
5. TELEM_* env

Both deprecated files still apply and each says so once per edit, naming the file to move it into. Level 3 sits deliberately above level 4, so migrating cannot silently change behavior. Credentials are env-only.

The skill's standalone CLI scripts read the same unified files (levels 1, 4 and 5 above) per invocation, taking the project from the directory you run them in; the deprecated .pi/ files and the trust gate are extension-only, because a CLI has no host to ask.

File key	Env var	Meaning
tier	TELEM_TIER	Named result-field tier
fields	TELEM_FIELDS (csv)	Explicit result fields (mutually exclusive with tier; the more specific level wins, fields on a tie)
providersInclude	TELEM_PROVIDERS_INCLUDE (csv; deprecated alias TELEM_PROVIDERS)	Replace the deployment's provider set
providersExclude	TELEM_PROVIDERS_EXCLUDE (csv)	Subtract providers
fullContent	TELEM_FULL_CONTENT=1	Ask providers for full content
providerOverrides	—	Raw per-provider request params. Applies only alongside providersInclude, and only to providers named there; anything else is dropped with a warning (see below)
—	TELEM_BASE_URL	Telem deployment base URL
—	TELEM_API_KEY	Bearer token

Example <project>/.telem/telem.json:

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

The providerOverrides contract. An override is only meaningful for a provider the request actually selects, and the resolved providersInclude is the only statement of that set the extension holds — with providersInclude unset, your account's own default provider set is running and the extension cannot enumerate it, so it forwards nothing it cannot check. Note that naming a provider is also a replacement: providersInclude swaps your account's default provider set for exactly the list you write, rather than adding to it.

{ "providersInclude": ["exa"], "providerOverrides": { "exa": { "numResults": 2 } } }

Troubleshooting

Symptom	Cause / fix
Agent uses bash curl instead of the tools	Package not loaded — pi list to check, /reload after installing, verify the project is trusted for project-local installs.
Telem search failed: HTTP 401/403	Missing/invalid TELEM_API_KEY.
…without the normalized search envelope (normalized_schema_version=…)	The endpoint predates the normalized search envelope. Check TELEM_BASE_URL points at https://router.telem.ai. This is a deliberate hard stop — rendering such an answer would silently look like "no results".
HTTP 400 … use search.providers	Provider names are reaching the backend through a legacy path; check your TELEM_PROVIDERS* values are plain provider names.
[provider] failed: … lines in results	That provider errored server-side; other providers' rows are unaffected. Purely informational.
No results found.	The query genuinely returned nothing — try rephrasing; check providersInclude isn't over-restricting (it REPLACES your account's provider set).
Config edits seem ignored	Check precedence, which is per key (a project file shadows the user files + env only for the keys it sets); check the file is valid JSON (a warning is printed once per broken edit); project files need project trust.
Both tier and fields warning	You configured both. Keep one, or accept the documented tie-break.

License

Copyright (c) 2026 Telem AI. Licensed under the Apache License, Version 2.0.