@jmcombs/pi-grok-search

Pi extension that performs real-time web search via the xAI Grok API.

Packages

Package details

extension

Install @jmcombs/pi-grok-search from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@jmcombs/pi-grok-search
Package
@jmcombs/pi-grok-search
Version
1.1.1
Published
May 25, 2026
Downloads
607/mo · 18/wk
Author
jmcombs
License
MIT
Types
extension
Size
11.5 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ],
  "image": "https://raw.githubusercontent.com/jmcombs/pi-extensions/main/assets/grok-search/preview.png"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@jmcombs/pi-grok-search

A Pi coding agent extension that adds real-time web search via the xAI Grok Agent Tools API.

Install

# Globally (recommended)
pi install npm:@jmcombs/pi-grok-search

# For a single session, without installing
pi -e npm:@jmcombs/pi-grok-search

An xAI API key is required. Sign up at x.ai to get one, then configure it using one of the methods below.

What It Adds

  • Tool: grok_search — performs a web search using the xAI Grok Agent Tools API to get real-time information from the internet. The tool is callable by the LLM whenever it needs current information from the public web.

Configuration

You must configure an xAI API key. Pi resolves the key in this order:

  1. AuthStorage under the xai_search key (preferred when using a dedicated key) or xai key (reuses your existing xAI model provider key) — recommended.
  2. The XAI_API_KEY environment variable.

Option 1 — ~/.pi/agent/auth.json (recommended)

Plain key (dedicated)

{
  "xai_search": {
    "type": "api_key",
    "key": "xai-..."
  }
}

Reuse existing xAI key (from model provider)

{
  "xai": {
    "type": "api_key",
    "key": "xai-..."
  }
}

Shell-resolved key (macOS Keychain)

{
  "xai_search": {
    "type": "api_key",
    "key": "!security find-generic-password -ws xai_search"
  }
}

Shell-resolved key (1Password)

{
  "xai_search": {
    "type": "api_key",
    "key": "!op read 'op://Personal/xai_search/credential'"
  }
}

The !-prefixed value is executed by your shell at lookup time, so no secret is ever stored on disk in plaintext.

Option 2 — environment variable

export XAI_API_KEY="xai-..."

Behavior Notes

  • Uses the current xAI Responses + Agent Tools API (web_search tool).
  • The tool honors Pi's abort signal — pressing Esc during a search cancels the HTTP request.
  • If the API key is missing the tool returns an error result with a helpful configuration hint instead of throwing.
  • Non-2xx responses from xAI surface as tool errors (with status, status text, and response body) rather than throwing.
  • Running /grok_authenticate allows you to choose between reusing your existing xai key or storing a dedicated key under xai_search.

Requirements

  • Pi >= 0.72.0 (uses AuthStorage and ExtensionAPI)
  • Node >= 22.0.0
  • An xAI API key

Development

This package lives in the pi-extensions monorepo.

# From the repo root
npm ci
npm run check       # full quality gate

# Try local changes against a real pi session
pi -e ./packages/grok-search

The smoke test in index.test.ts does not mock the xAI API; it only verifies registration shape. Real end-to-end behavior is exercised via pi -e.

License

MIT © Jeremy Combs