Coding agents
Codex
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.
Before you begin
Section titled “Before you begin”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
- Open your project
- API keys
- Issue API key
tlm_••••••••••••••••Keys start with tlm_.
Never paste a key into a chat with Codex. Every path below sets it for you.
Install
Section titled “Install”Connect Codex to Telem
-
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 | shTerminal window npx @telemai/create@latestIn PowerShell, with Node.js 20 or later. Or run the macOS and Linux command in WSL or Git Bash.
-
Restart Codex. Codex loads the server and the plugin when it starts.
-
Check the connection.
telemis in the list.Terminal window codex mcp list
Install with no prompts, for example in CI
curl -fsSL https://docs.telem.ai/install.sh | sh -s -- --yes --client codex --key-env TELEM_API_KEYnpx @telemai/create@latest --yes --client codex --key-env TELEM_API_KEYIn PowerShell, with Node.js 20 or later. Or run the macOS and Linux command in WSL or Git Bash.
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.
-
Add the server with your key, then add the plugin. Put this table in
~/.codex/config.toml, with your key in place oftlm_your_key:~/.codex/config.toml [mcp_servers.telem]url = "https://mcp.telem.ai/mcp"http_headers = { Authorization = "Bearer tlm_your_key" }Terminal window codex plugin marketplace add TelemAI/codex-plugincodex plugin add telem@telem -
Restart Codex. Codex loads the server and the plugin when it starts.
-
Check the connection.
telemis in the list.Terminal window codex mcp list
Codex skips a plugin hook that it does not trust, and it does not tell you. The
installer trusts the Telem hook for you. After a by-hand install, open Codex, run
/plugin, and trust the telem hook. Codex then updates the plugin by itself, and you
trust the hook again after each update: see Update and remove.
-
Start Codex with your key set, and paste this prompt. Codex runs the installer, which reads the key from
TELEM_API_KEY, so the key never goes into the chat.Terminal window export TELEM_API_KEY=tlm_your_keycodexTerminal window $env:TELEM_API_KEY = "tlm_your_key"codexSet 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 itsvalue. 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 codex --key-env TELEM_API_KEYOn Windows, in PowerShell, run this instead:npx @telemai/create@latest --yes --client codex --key-env TELEM_API_KEY4. Show me the installer's summary. Then tell me to restart Codex,so that the Telem tools load. -
Restart Codex. Codex loads the server and the plugin when it starts.
-
Check the connection.
telemis in the list.Terminal window codex mcp list
If it does not work, see If something goes wrong.
Search and read
4 toolstelem_searchSearches the web on several providers in one call.telem_fetchReads the full text of up to 5 pages.telem_providersLists the search providers.telem_session_historyLists the earlier searches in a session.
Monitors
8 toolsmonitor_createCreates a monitor. Its agent keeps the results that match.monitor_listLists your monitors that have an agent.monitor_getGets a monitor and its agent.monitor_agentGets the agent: its status, its plan and what it found.monitor_changesReads what the agent found, change by change.monitor_pausePauses a monitor.monitor_resumeResumes a paused monitor.monitor_deleteEnds 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.
Specific to Codex
Section titled “Specific to Codex”- Keep the server name
telem. The Telem hook runs only for tools namedmcp__telem__telem_searchandmcp__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.
Update and remove
Section titled “Update and remove”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:
codex plugin marketplace upgrade telemAfter 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:
codex plugin remove telem@telemcodex plugin marketplace remove telemcodex mcp remove telemRestart 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. |
Learn more
Section titled “Learn more”Set the tier, the providers and auto-routing in one file, for Codex and your other agents.
Every option, the values it takes, and which setting wins.
What each search option does, from tiers to date windows.
Choose the fetch provider and tier, or read pages live.