Skip to content

Coding agents

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.

  • 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

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

Connect Grok Build to Telem

  1. Run the installer in your terminal. If it shows a menu, 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 switch Grok’s default web search and fetch to Telem, 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
  2. 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.

  3. 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
Terminal window
curl -fsSL https://docs.telem.ai/install.sh | sh -s -- --yes --client grok --key-env TELEM_API_KEY --grok-allow-telem

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 Grok Build at that MCP url instead of https://mcp.telem.ai/mcp, and saves both urls for later runs.

--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 keeps its own web search and fetch as the default. Add --grok-disable-web-search to switch the default search and fetch to Telem too.

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.

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.

  • 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 default web search and fetch. If you say yes, the installer switches them to Telem: it sets disable_web_search = true at the top of ~/.grok/config.toml. Grok’s model then has no web search or page fetch of its own, and uses Telem’s. 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.

To update, run the installer again. It rewrites the hook and the skill when they changed. If your saved key still works, it uses it and does not ask.

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