Pi

The @telemai/pi-telem package adds web search and page reading to Pi. Its skill tells Pi when to use them.

Before you begin

Node.js 20 or later. The installer checks for it and offers to install it.

Create a Telem API key

1. Open your project
2. API keys
3. Issue API key

tlm_••••••••••••••••Keys start with tlm_.

Open the console

Never paste a key into a chat with Pi. Every path below sets it for you.

Install

Connect Pi to Telem

Installer

1. Run the installer in your terminal. If it shows a menu, pick pi. Paste your key when the installer asks. The field is masked, and the key never appears on screen.

   macOS and Linux

   curl -fsSL https://docs.telem.ai/install.sh | sh

   Windows

   npx @telemai/create@latest

   In PowerShell, with Node.js 20 or later. Or run the macOS and Linux command in WSL or Git Bash.

2. Restart Pi, or type /reload in an open session. Pi loads packages when it starts.

3. Check the install. @telemai/pi-telem is in the list.

   pi list

Install with no prompts, for example in CI

macOS and Linux

curl -fsSL https://docs.telem.ai/install.sh | sh -s -- --yes --client pi --key-env TELEM_API_KEY

Windows

npx @telemai/create@latest --yes --client pi --key-env TELEM_API_KEY

In PowerShell, with Node.js 20 or later. Or run the macOS and Linux command in WSL or Git Bash.

By hand

1. Install the package and set your key. Pi reads the key from TELEM_API_KEY, so set it in the shell you start Pi from.

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

2. Restart Pi, or type /reload in an open session. Pi loads packages when it starts.

3. Check the install. @telemai/pi-telem is in the list.

   pi list

Ask your agent

1. Start Pi with your key set, and paste this prompt. Pi runs the installer, which reads the key from TELEM_API_KEY, so the key never goes into the chat.

   macOS and Linux

   export TELEM_API_KEY=tlm_your_key
   pi

   Windows

   $env:TELEM_API_KEY = "tlm_your_key"
   pi

   Set up Telem web search for this coding agent.
   
   1. Read https://docs.telem.ai/llms.txt to learn what Telem is.
   2. Check that the TELEM_API_KEY environment variable is set. Do not print its
      value. If it is not set, stop and ask me to set it and restart you.
   3. Run the Telem installer for this agent, with no prompts:
      curl -fsSL https://docs.telem.ai/install.sh | sh -s -- --yes --client pi --key-env TELEM_API_KEY
      On Windows, in PowerShell, run this instead:
      npx @telemai/create@latest --yes --client pi --key-env TELEM_API_KEY
   4. Show me the installer's summary. Then tell me to restart Pi,
      so that the Telem tools load.

2. Restart Pi, or type /reload in an open session. Pi loads packages when it starts.

3. Check the install. @telemai/pi-telem is in the list.

   pi list

If it does not work, see If something goes wrong.

Tools

Search and read

2 tools

• telem_search Searches the web on several providers in one call.
• telem_fetch Reads the full text of up to 5 pages.

Specific to Pi

• A skill with its own scripts. The package also has the telem skill (/skill:telem). Its scripts, scripts/search.mjs and scripts/fetch.mjs, need nothing but Node.js, and they work where the extension is not installed. They send no query lineage. When the extension’s tools are there, the skill tells the agent to use them.
• Project settings need a trusted project. The extension reads a project’s .telem/telem.json only when Pi trusts the project. If Pi cannot tell, the project counts as untrusted. Your user file and the TELEM_* variables still apply.
• The scripts read the folder you run them in. They have no trust check, and they read only .telem/telem.json, ~/.telem/telem.json and the TELEM_* variables. Notices go to stderr, so stdout holds only results. search.mjs also takes --published-after and --published-before (ISO 8601 dates), and --goal.

Update and remove

To update, run the installer again, or update the package. A bare pi update updates only Pi itself.

pi update npm:@telemai/pi-telem

To remove it:

pi remove npm:@telemai/pi-telem

This uninstalls the package and removes it from ~/.pi/agent/settings.json. For a project install, add -l. Restart Pi after you update or remove.

What the installer changed outside the package

File	What it holds	To undo
~/.telem/credentials.json	Your key	Delete it if no other Telem integration uses it.
~/.telem/telem.json	Your Telem options	Delete it if no other Telem integration uses it.
~/.telem/update-notice.json	When the plugin last told you about an update	Delete it with the files above.

Learn more

Configuration

Set the tier, the providers and auto-routing in one file, for Pi and your other agents.

Parameters

Every option, the values it takes, and which setting wins.

Search parameters

What each search option does, from tiers to date windows.

Fetch parameters

Choose the fetch provider and tier, or read pages live.