Skip to content

Coding agents

Telem adds web search, page reading and monitors to Codex. The tools come from Telem’s hosted MCP server, and the Telem plugin sends your options with each search.

Node.js 20 or later. The installer checks for it and offers to install it. The plugin uses it to send your Telem options with each search.

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 Codex. Every path below sets it for you.

Connect Codex to Telem

  1. Run the installer in your terminal. If it shows a menu, pick Codex. Paste your key when the installer asks. The field is masked, and the key never appears on screen. The installer also asks whether to switch Codex’s default web search and fetch to Telem.

    Terminal window
    curl -fsSL https://docs.telem.ai/install.sh | sh
  2. Restart Codex. Codex loads the server and the plugin when it starts.

  3. Check the connection. telem is in the list.

    Terminal window
    codex mcp list
Install with no prompts, for example in CI
Terminal window
curl -fsSL https://docs.telem.ai/install.sh | sh -s -- --yes --client codex --key-env TELEM_API_KEY

For a private deployment, add its two urls: --base-url https://router.example.com --mcp-url https://mcp.example.com/mcp, for example. The installer points Codex at that MCP url instead of https://mcp.telem.ai/mcp, and saves both urls for later runs.

Search and read

4 tools
  • telem_search Searches the web on several providers in one call.
  • telem_fetch Reads the full text of up to 5 pages.
  • telem_providers Lists the search providers.
  • telem_session_history Lists the earlier searches in a session.

Monitors

8 tools
  • monitor_create Creates a monitor. Its agent keeps the results that match.
  • monitor_list Lists your monitors that have an agent.
  • monitor_get Gets a monitor and its agent.
  • monitor_agent Gets the agent: its status, its plan and what it found.
  • monitor_changes Reads what the agent found, change by change.
  • monitor_pause Pauses a monitor.
  • monitor_resume Resumes a paused monitor.
  • monitor_delete Ends a monitor.

Codex runs the search and read tools without asking. It asks before monitor_create, monitor_pause, monitor_resume and monitor_delete, because they change your monitors, and codex exec, which never asks, refuses those four.

  • Keep the server name telem. The Telem hook runs only for tools named mcp__telem__telem_search and mcp__telem__telem_fetch. If you rename the [mcp_servers.telem] table, the tools still work, but the plugin sends no options and no reasoning.
  • The console shows why Codex searched. The plugin sends Codex’s reasoning summary with each search. That is why the installer sets model_reasoning_summary = "detailed": without it, Codex writes no summaries.

To update, run the installer again. If your saved key still works, it uses it and does not ask. The installer also trusts the new version of the hook, so Codex keeps running it.

If you installed by hand, Codex updates the Telem plugin by itself: when a new version is out, Codex gets it when it starts. To update at once:

Terminal window
codex plugin marketplace upgrade telem

After each update, by Codex or by you, Codex shows Hooks need review: choose Trust all and continue. Until you do, Codex skips the plugin’s hook. codex exec does not show this, so open Codex once to trust the hook.

To remove Telem:

Terminal window
codex plugin remove telem@telem
codex plugin marketplace remove telem
codex mcp remove telem

Restart Codex after you update or remove.

What the installer changed outside the plugin
Where 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.
~/.codex/config.toml web_search = "disabled", if you said yes Remove the line, or Codex has no web search after you remove Telem.
~/.codex/config.toml model_reasoning_summary = "detailed", if it was not set Remove the line.
~/.codex/config.toml The trust entry for the telem hook, under [hooks.state] Remove the entry.
Configuration

Set the tier, the providers and auto-routing in one file, for Codex 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.

Was this page helpful?