JangMan-J/pi-grok-agent
Grok Build as a model in Pi. Grok keeps his tools, so Pi can put him to work. - JangMan-J/pi-grok-agent
0 stars · 0 forks
README
pi-grok-agent Grok's agent. Pi's workflow. 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. 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 Agent Client Protocol over WebSockets. Grok returns streaming responses, thinking blocks, as well as image and video requests. All of Grok's tool requests are routed back to Pi through callbacks 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 decisions. Grok's tool call requests, turn order, user_ask_question prompts are delegated to Pi. Grok can use Pi's extension tools Lent over MCP as pi__<name>, with the result continuing the same Grok turn. Grok keeps all of his tools and extensions. My own observations have been that Grok performs better with his native toolset, so this project's purpose is to keep his tools without buying the shed.
Models
Model ID Name in /models Reasoning efforts Context window
grok/grok-4.7 Grok 4.7 low, medium, high, xhigh 500,000 tokens
grok/grok-4.7-build-fast Grok 4.7 Build Fast low, medium, high, xhigh 500,000 tokens
grok/grok-4.6 Grok 4.6 low, medium, high, xhigh 500,000 tokens
grok/grok-4.5 Grok 4.5 low, medium, high, xhigh 500,000 tokens
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. The ACP protocol does not provide 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. The postEditCheck and stopCheck settings run as shell commands — treat them as executable code.
Notes
Not compatible with API key access. A Grok account is required, any membership tier. If your OAuth token expires you can '/login' from either Grok Build or Pi with '/grok login' to renew credentials. Token read, token write, cache read and cache hit % displayed in Pi are taken from Grok Build. Pi may occasionally report inaccurate data during long multistep tool calls, but will correct onn 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.