pi

Coming soon

This package is not yet on the public npm registry. Contact the Telem team for early access.

@telem/pi-telem adds telem_search and telem_fetch as agent tools in the pi coding agent, both backed by the same POST /v1/interactions endpoint the rest of Telem uses, plus a companion skill that works even in harnesses where the extension itself isn’t loaded.

Prerequisites

• Node.js 22+
• pi installed and working — npm install -g --ignore-scripts @earendil-works/pi-coding-agent.

Install

1. 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.

2. Install with the npm: prefix. The prefix is required — pi install @telem/pi-telem (bare package name) is rejected, because pi reads a bare name as a local path rather than an npm source.

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

4. Reload if pi was already running. Type /reload inside an open pi session so it picks up the newly installed package; a fresh pi start doesn’t need this.

pi install npm:@telem/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, recorded into the same Telem trajectory model, adapted to pi’s session and branching model.
• 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.

Configuration

TELEM_BASE_URL defaults to the hosted Telem service at https://router.telem.ai when unset. Options resolve per tool call — no pi restart needed — with precedence, per key:

1. project .pi/telem.json (trusted projects only)
2. ~/.config/pi/telem.json
3. 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 a warning is printed.

Example .pi/telem.json, shareable with your team:

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

Troubleshooting

Agent uses bash curl instead of the tools

The package isn’t loaded. Run pi list to confirm @telem/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 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 .pi/telem.json shadows the home config and the environment, but only applies in a trusted project. 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 (the more specific source wins; fields on a tie).