pi-grok-agent

pi install npm:pi-grok-agent

Run Grok Build as an additional model provider in Pi coding agent. Grok keeps its native environment, tools, and session history. Pi provides the DIY harness, turn control, permission requests, and extensions.

Play the demo video

How it connects

┌─────────────────────┐         ┌──────────────────┐         ┌─────────────────────┐
│ PI — drives turn    │         │ GATEWAY          │         │ GROK BUILD — works  │
│ transcript, gates,  │  ACP    │ one per machine  │  stdio  │ own tools, agents,  │
│ dialogs             │ over WS │ 127.0.0.1:2419   │         │ own history         │
│ grok provider ext   │◄───────►│ guard + MCP      │◄───────►│ ~/.grok login       │
└─────────────────────┘         └──────────────────┘         └─────────────────────┘

Pi drives the session using the Agent Client Protocol over WebSockets. Grok streams back its responses, thinking blocks, as well as any images and videos it generates. Grok runs its own tools, but asks Pi through a hook before each call, and Pi can allow or deny it. Pi's extension tools are lent to Grok over an MCP loopback. The first Grok turn auto-starts the local gateway (127.0.0.1:2419 by default); every Pi process on the machine attaches to it. Details: docs/architecture-diagram.md · docs/usage.md.

Function

• Pi sets permissions and boundaries. Read-only, ask, auto, and YOLO permission modes are supported.
• Pi makes the decisions. Pi allows or denies each of Grok's tool calls. In interactive Pi, Grok's permission prompts and ask_user_question prompts open as Pi dialogs.
• Grok can use Pi's extension tools. They are lent over MCP as pi__<name>, and the result continues the same Grok turn.
• Grok keeps all of its tools and extensions. My own observations have been that Grok performs better with its native toolset, so this project's purpose is to keep its tools without buying the shed.

Models

Each model's context window is read from Grok Build's model cache (~/.grok/models_cache.json) when the extension loads.

Model availability in Pi is determined by your account access.

Safety

• This package connects the Grok Build agent over ACP, not the xAI chat-completions API. ACP does not give complete visibility or control of an agent, and not all functions or extensions of Grok Build have been tested for safety in this configuration. The tool gates are not an operating-system sandbox: Grok runs with your user's permissions.
• The gateway listens on loopback only, requires a bearer secret, and never starts Grok with --always-approve. Headless use does not imply approval: by default, headless Pi cancels Grok's permission prompts. /grok perms yolo selects allow once for those prompts. The postEditCheck and stopCheck settings run as shell commands, so treat them as executable code.

Notes

• Not compatible with API key access. A Grok account is required, any membership tier. If your login expires, run /login in Grok Build or /grok login in Pi to renew it.
• The input, output, cache read, and cache write token counts and the cost shown in Pi come from Grok Build's usage report. Pi may occasionally report inaccurate data during long multistep tool calls, but will correct on the next turn.

Documentation

• docs/usage.md: settings, lent tools, permissions, the gateway guard, hooks, /grok commands, troubleshooting
• docs/architecture-diagram.md: the diagram in mermaid and ASCII
• docs/first-class-model.md: design and turn mapping
• docs/launch-verification.md: recorded live runs behind the verified claims

Feedback

Open an issue with the output of node --version, pi --version, and grok --version, the model ID, and a short redacted excerpt of /grok debug.

License

Apache License 2.0