pi-grok-sdk

Use Grok Build inside pi via the local xAI agent CLI — real agent tools, multi-turn ACP sessions, and native thinking/text streaming.

Packages

Package details

extension

Install pi-grok-sdk from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:pi-grok-sdk

Package: pi-grok-sdk
Version: 0.2.1
Published: Jul 12, 2026
Downloads: 47/mo · 47/wk
Author: ankitchouhan1020
License: MIT
Types: extension
Size: 58.2 KB
Dependencies: 0 dependencies · 2 peers

Pi manifest JSON

{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

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

README

pi-grok-sdk

Use Grok Build inside pi without giving up the agent that already knows your machine.

pi-grok-sdk wires pi to the local xAI agent CLI (agent / grok). You get pi’s model picker, sessions, and streaming UI; Grok keeps its tools, skills, MCP servers, permissions, and multi-turn loop. Inference is not a thin HTTP chat wrapper — it’s the real local agent runtime, streamed back as native pi events.

Models: grok-sdk/grok-4.5 (and others from agent models)

Requirements

pi 0.80.6+
Node 22.19+
Grok agent CLI installed and logged in

which agent || which grok
agent --version
agent models

If the binary only lives under ~/.grok/bin, add it to PATH or set PI_GROK_SDK_BIN.

Install

pi install npm:pi-grok-sdk

Alternatives:

pi install https://github.com/ankitchouhan1020/pi-grok-sdk
pi install /path/to/pi-grok-sdk   # local checkout

pi remove npm:pi-grok-sdk

Quick start

pi --list-models grok-sdk

pi --model grok-sdk/grok-4.5
pi --model grok-sdk/grok-4.5 -p "Say hi"
pi --model grok-sdk/grok-4.5 --thinking high -p "…"

Smoke test:

pi --model grok-sdk/grok-4.5 --no-session -p \
  "Reply exactly PI_GROK_OK and nothing else."

Optional defaults in ~/.pi/agent/settings.json:

{
  "defaultProvider": "grok-sdk",
  "defaultModel": "grok-4.5"
}

Commands

Command	What it does
`/grok-sdk status`	Binary, auth, mode, models
`/grok-sdk models`	Live CLI model list
`/grok-sdk mode`	Current mode + env hints
`/grok-sdk refresh-models`	Re-discover models

/grok-agent is an alias for /grok-sdk.

How it works

pi  ──streamSimple──►  pi-grok-sdk
                          │
                          ├─ acp (default)  long-lived agent agent … stdio
                          │                 multi-turn session pool
                          │                 thinking → text (native pi events)
                          │
                          └─ jsonl          one-shot --single streaming-json

ACP (default) keeps a long-lived Grok process per pi session (model + cwd + effort). Turns speak ACP over stdio; later messages only send new user content so Grok retains history and tools.

JSONL is a one-shot fallback for debugging:

PI_GROK_SDK_MODE=jsonl pi --model grok-sdk/grok-4.5 -p "…"

Streaming is pi-native: token deltas, thinking closed before the answer, and event-loop yields so the TUI can paint mid-stream.

Config

Env	Default	Meaning
`PI_GROK_SDK_MODE`	`acp`	`acp` or `jsonl`
`PI_GROK_SDK_BIN`	—	Path to `agent` / `grok`
`PI_GROK_SDK_SHOW_TOOLS`	off	Show Grok tool titles as short thinking notes

Aliases still work: PI_GROK_AGENT_MODE, PI_GROK_AGENT_BIN, etc.

Binary lookup: env → PATH (agent, grok) → ~/.grok/bin.

Pi --thinking maps to Grok --reasoning-effort (off / minimal / low / medium / high / xhigh / max).

Compat

Legacy provider id: grok-agent-cli/… (same models)
Legacy model id: grok-4.5-agent → grok-4.5
Text-only input for now

Not in scope

Pi tools are not bridged into Grok (Grok runs its own tools)
Not an xAI HTTP / OpenAI-compatible API
No image input yet

Troubleshooting

Problem	Fix
No models	Check package path in settings; restart pi
CLI not found	`which agent` or `PI_GROK_SDK_BIN`
Auth errors	Run `agent` / `grok login` once in a terminal
Stale models	`/grok-sdk refresh-models`