Coding agents

Grok Build

Telem adds web search, page reading and monitors to Grok Build, xAI’s coding agent for the terminal. The tools come from Telem’s hosted MCP server. A Telem hook sends your options with each search, and records why Grok searched when the model gives its reasoning.

Before you begin

Grok Build 1.0.64 or later. Telem is tested on 1.0.70. To install Grok Build, run curl -fsSL https://x.ai/cli/install.sh | bash or npm i -g @xai-official/grok.
Node.js 20 or later, on the PATH that Grok runs with. The installer checks for it and offers to install it. The hook runs on it.

Create a Telem API key

Open your project
API keys
Issue API key

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

Open the console

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

Install

Connect Grok Build to Telem

Run the installer in your terminal and pick Grok Build. Paste your key when the installer asks. The field is masked, and the key never appears on screen. The installer also asks whether to turn off Grok’s own web search, and whether to let Grok run Telem searches and page reads without asking each time.
Terminal window
```
curl -fsSL https://docs.telem.ai/install.sh | sh
```
Start Grok Build in your project, and trust the folder when Grok asks. Grok reads its config when it starts. It runs the Telem hook only in a folder you trust.
Check the connection. Grok connects to Telem and finds 8 tools. This runs no search. Then ask Grok to search the web: the search shows in the console.
Terminal window
```
grok mcp doctor telem
```

Install with no prompts, for example in CI

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

--grok-allow-telem lets Grok run telem_search and telem_fetch without asking. Without it, a headless grok -p run cancels every Telem call. With --yes, Grok’s own web search stays on. Add --grok-disable-web-search to turn it off too.

Add the server with your key. Put this table in ~/.grok/config.toml, with your key in place of tlm_your_key:
~/.grok/config.toml
```
[mcp_servers.telem]
url = "https://mcp.telem.ai/mcp"
headers = { Authorization = "Bearer tlm_your_key" }
```
To let Grok run Telem searches and page reads without asking, add these rules too. If the file already has a [permission] table, add the two rules to its allow list instead.
~/.grok/config.toml
```
[permission]
allow = ["MCPTool(telem__telem_search)", "MCPTool(telem__telem_fetch)"]
```
Start Grok Build. Grok reads its config when it starts.
Check the connection. Grok connects to Telem and finds 8 tools. This runs no search. Then ask Grok to search the web: the search shows in the console.
Terminal window
```
grok mcp doctor telem
```

This gives Grok the tools, but not the hook: your .telem/telem.json options and the reasoning are not sent. The installer adds the hook.

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

export TELEM_API_KEY=tlm_your_key
grok

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 grok --key-env TELEM_API_KEY
4. Show me the installer's summary. Then tell me to restart Grok Build,
   so that the Telem tools load.

Start Grok Build again, and trust the folder when Grok asks. Grok reads its config when it starts. It runs the Telem hook only in a folder you trust.
Check the connection. Grok connects to Telem and finds 8 tools. This runs no search.
Terminal window
```
grok mcp doctor telem
```

The prompt installs with no questions, so Grok asks before each Telem call. To stop that, add the [permission] rules from the By hand tab. If it does not work, see If something goes wrong.

Tools

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

4 tools

create_monitor Runs a search on a schedule and keeps only new results.
list_monitors Lists your monitors.
get_new_results Gets the new results of a monitor since the last read.
delete_monitor Deletes a monitor.

Grok Build asks before it runs an MCP tool, the search and read tools too. If you said yes to the installer’s question, Grok runs telem_search and telem_fetch without asking. It still asks before the other six tools. A headless grok -p run cancels a call that needs your approval.

Specific to Grok Build

Trust the folder. Grok runs the Telem hook only in a folder you trust. While the hook is installed, Grok asks you to trust each new folder, except your home folder. In a folder that you do not trust, Telem searches still work, but without your options, and the console does not show their session or reasoning. A headless grok -p run counts the folder as trusted.
Options come from the files and your shell. The hook reads the project’s .telem/telem.json, then ~/.telem/telem.json, then the TELEM_* variables: Grok gives your shell’s environment to the hook. It sends your options with every search and page read, the fetch keys included. providerOverrides is not sent.
Why Grok searched. The hook sends the reasoning that led to each search, when the model gives its reasoning. If it gives none, the hook sends the text Grok wrote before the search, if there is any.
Grok’s own web search. If you say yes, the installer sets disable_web_search = true at the top of ~/.grok/config.toml. This turns off Grok’s own web search and page fetch. X search stays on. If you add the line by hand, put it above the first [table]: under a table header, it does nothing.
Long results are cut. Grok cuts an MCP result at 20,000 bytes, and keeps the full result in the session folder. A search with many queries can be longer. To change the limit, set max_output_bytes under [mcp] in ~/.grok/config.toml. The limit applies to every MCP server.
Keep the server name telem. The model reaches the tools through Grok’s use_tool, as telem__telem_search, telem__telem_fetch and so on, and search_tool shows their inputs. Grok lists the server as “telem (8 tools)”. The hook and the allow rules use these names. If you rename the [mcp_servers.telem] table, the tools still work, but the hook sends no options or reasoning, and Grok asks before each call.
GROK_HOME. If you set it, the installer writes to that folder instead of ~/.grok.

If something goes wrong

401 on every call: the server’s Authorization header is missing or has an old key. Run the installer again, or edit the header. After grok mcp disable or grok mcp enable, the headers are in a [mcp_servers.telem.headers] table: edit the key there. A header that names a variable, such as "Bearer ${TELEM_API_KEY}", works only when the variable is set when Grok starts. If it is not set, Grok sends the text as it is.
Searches show without their session or reasoning: the folder is not trusted, or node is not on the PATH that Grok runs with. The search still runs, without your options.
Grok asks before every Telem call, or grok -p cancels them: add the [permission] rules from the By hand tab, or run the installer again and say yes.
“Hook denied: [telem] providersExclude removes every provider”: your options exclude every provider that they include. See When include and exclude name the same provider.

Update and remove

To update, run the installer again. It rewrites the hook and the skill when they changed. You can keep the key you already have.

To remove Telem, take these out of ~/.grok/config.toml:

the [mcp_servers.telem] table, and [mcp_servers.telem.headers] if Grok wrote one;
the [permission] table if the installer added it, or the two Telem rules if you added them to your own allow list;
disable_web_search = true, if the installer set it and you want Grok’s own web search back.

Then delete hooks/telem.json, the telem folder and the skills/telem folder in ~/.grok/, and start Grok again. Grok then has no Telem server, skill or hook.

What the installer changed outside Grok’s config

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.

Learn more

Configuration

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