Pi Grok Build

Use Grok Build from Pi as a managed collaborator.

pi-grok-build is a Pi package that gives Pi one tool, grok_build, for delegating review, research, candidate edits, and media work to Grok Build without leaving the Pi session. Pi stays the parent agent: it starts Grok work, waits for results, sends follow-ups, inspects artifacts, cancels stale work, and decides what to accept.

The package is source-inspectable and deliberately small:

• grok_build for model-facing delegation;
• /grok-build for human diagnostics;
• a fixed widget for active sessions, failures, and diagnostics;
• retained artifacts for answers, copied inputs, generated media, and edit diffs;
• explicit consent before prompt-carrying work goes to Grok/xAI.

The backend runtime is grok agent stdio over ACP. No grok -p, raw xAI API path, TUI scraping, relay, or fallback runtime is part of the product.

Install

From npm:

pi install npm:pi-grok-build

From a local checkout:

pi install /absolute/path/to/pi-grok-build

Reload Pi after installation or source changes before expecting the active tool surface to change.

Delegate with grok_build

Model-facing tool:

grok_build

Actions:

start | send | status | result | changes | cancel | cleanup

Use it when the Pi parent should ask Grok Build to do sidecar work:

• get a second review of a local repository;
• run grounded research through Grok;
• prepare candidate edits in an isolated worktree;
• generate or edit media and return artifact paths;
• continue the same Grok session with follow-up instructions.

doctor and preflight are not model-facing actions. They are human diagnostics under /grok-build.

Human command

/grok-build doctor
/grok-build preflight
/grok-build status g1
/grok-build result g1
/grok-build changes g1
/grok-build cancel g1
/grok-build cleanup g1

/grok-build start and /grok-build send ask for interactive confirmation before sending prompt-carrying work to Grok/xAI.

Profiles

Choose the narrowest profile that can do the job.

| Profile | Use for | Writes | Web/current evidence | Media | | --- | --- | ---: | ---: | ---: | | local-review | local source or repo review | no | no | no | | grounded-review | repo review with current external evidence | no | yes | no | | deep-research | broader research or decomposition | no | yes | no | | worktree-edit | candidate edits without web | yes | no | no | | grounded-edit | candidate edits with current evidence | yes | yes | no | | media | image/video generation or editing | artifact only | no by default | yes |

Typical use

Delegate a review:

{
  "action": "start",
  "cwd": "/absolute/git/workspace",
  "profile": "local-review",
  "task": "Review this repository for API drift and report the highest-risk findings.",
  "confirm_provider_use": true
}

Wait for the collaborator's answer:

{ "action": "result", "session": "g1", "wait_seconds": 30, "preview": true }

Send a follow-up into the same Grok session:

{
  "action": "send",
  "session": "g1",
  "task": "Now focus on the CLI surface and release risks.",
  "confirm_provider_use": true
}

Inspect candidate edit-session changes:

{ "action": "changes", "session": "g1", "preview": true }

Stop and remove retained evidence:

{ "action": "cancel", "session": "g1", "reason": "User stopped the run." }
{ "action": "cleanup", "session": "g1" }

Consent

start and send can send prompts, repository context, local artifacts, and selected tool behavior to Grok/xAI through the locally authenticated Grok CLI. They require confirm_provider_use:true after explicit current authorization.

Diagnostics, install checks, and old successful runs do not grant provider-use consent.

Worktrees

Write-capable profiles require a clean parent git repository. The package creates a session-owned assigned git worktree under its artifact root and launches Grok there. The parent repository is not the edit target. changes reads the assigned worktree and reports files and diff artifacts.

Root grok --worktree is not used as the isolation primitive, and there is no model-facing worktree knob.

Media

Media inputs are local image files only:

• accepted: absolute JPG, PNG, or WebP paths under the admitted workspace or a prior package artifact root;
• denied: URLs, GIF/HEIC/HEIF, inline payloads, credential/control roots, unsupported extensions, and images smaller than 8 px per side or 512 total pixels;
• transport: copied, hashed, checked, and sent as ACP embedded resource blobs after embeddedContext proof;
• output: generated image/video files returned by Grok are copied into package-owned turn media artifacts.

Widget

The fixed widget key is grok-build:fixed. It shows active sessions, failed sessions that need attention, and diagnostics. Completed and explicitly cancelled sessions are not alerts. The package does not use a footer status or dashboard shell.

Validation

For source/package changes run:

npm test
npm run check:pack
git diff --check

Live/provider proof is separate and requires explicit authorization before any prompt-carrying Grok run.