grok-pi — Remote TUI bridge for Pi and Grok Build

Pi agent core in Grok Build's native terminal UI.

Download latest release · ZH · Feature matrix · Architecture · Verification · Changelog · 更新日志

Remote TUI bridge. Pi's interactive components render through Grok Build's native Pager, preserving the Grok terminal experience while exposing Pi's extension ecosystem. Pi users get Grok Build's native UI; Grok Build users get Pi's models, tools, sessions, and extensions.

grok-pi combines Pi's agent runtime with Grok Build's native Pager. Pi remains responsible for models, tools, extensions, sessions, and agent execution. Grok Pager remains the only terminal UI.

curl -fsSL https://github.com/Dwsy/grok-pi/releases/latest/download/install.sh | sh

irm https://github.com/Dwsy/grok-pi/releases/latest/download/install.ps1 | iex

The installer picks the matching release asset and installs grok-pi:

Defaults: Unix → ~/.local/bin; Windows → %LOCALAPPDATA%\grok-pi\bin. Override with GROK_PI_INSTALL_DIR. Pin with GROK_PI_VERSION=vX.Y.Z.

The installer also creates pig and pi-grok aliases (Unix symlinks; Windows pig.exe / pi-grok.exe hardlinks with copy fallback):

pig --help # short alias
grok-pi --help # original name
pi-grok --help # alias

grok-pi requires Pi 0.84.3 or newer (system pi / pi.dev installer):

# recommended
curl -fsSL https://pi.dev/install.sh | sh
# Windows:
# powershell -c "irm https://pi.dev/install.ps1 | iex"
# or npm:
npm install --global @earendil-works/pi-coding-agent

On Windows, if an older grok-pi.exe cannot find bare pi, point it at the shim:

$env:PI_BIN = "$env:LOCALAPPDATA\pi-node\current\pi.cmd"
grok-pi --pi-bin $env:PI_BIN

From any project directory:

grok-pi
# or
pig
# or
pi-grok

Defaults: system pi on PATH, current working directory as the project. Continue the previous session with grok-pi --continue.

Useful commands:

grok-pi --help
grok-pi update --check
grok-pi update

For field-level behavior and intentional omissions, see the feature matrix.

flowchart LR
 User[Terminal user] <--> Pager[Grok Pager\nNative TUI]
 Pager <--> ACP[ACP]
 ACP <--> Adapter[pi-grok-adapter\nJSONL RPC ↔ ACP]
 Adapter <--> Pi[Pi\nAgent core]

The integration has three boundaries:

• Grok Pager owns terminal lifecycle, input, rendering, dialogs, and visible UI.
• Pi owns the agent loop, models, providers, tools, extensions, and sessions.
• pi-grok-adapter is a headless JSONL RPC ↔ ACP bridge. It does not own a terminal or render a second UI.

Pi source is not modified. The Remote TUI bridge connects capabilities unavailable in Pi RPC through the official extension API and projects them onto native Pager surfaces.

Bundled bridge extensions are enabled by default where stable. Experimental native commands are opt-in.

Subagents V2 team presets are JSON files under <repo>/.grok-pi/teams or ~/.grok-pi/teams (project overrides global, which overrides bundled presets). Agent profiles remain external Markdown under the matching agents/ directories. Example:

{
 "name": "implementation",
 "description": "Implementation plus review",
 "members": [
 { "name": "implementer", "agent": "general-purpose", "task": "Implement: {{task}}" },
 { "name": "reviewer", "agent": "explore", "task": "Review: {{task}}" }
 ]
}

Enable V2 before starting grok-pi with the F2 "Pi subagents V2" toggle or PI_GROK_SUBAGENTS_V2=1; use /subagent-teams to inspect presets. spawn_team starts a preset, while spawn_team_agent, team_send_message, team_followup_task, team_wait, team_list, and team_interrupt provide the lower-level collaboration surface. Rhai Workflow remains the deterministic orchestration engine; Team V2 is the session-scoped, run-reusable agent identity/messaging layer.

Rhai workflows are off by default (F2 → Agent → Pi workflows, then full restart). Details: FEATURE_MATRIX.md, AGENTS.md.

Herdr lifecycle reporting is off by default. Enable it with F2 → Agent → Pi Herdr integration, then restart. See the Herdr setup guide.

Use --no-extensions (-ne) to disable Pi extension auto-discovery; explicit -e paths and grok-pi host bridges still load. Use --no-bridge-extensions to disable the bundled host bridges, or combine both flags for a fully extension-free launch. Pi startup options can be passed directly after --.

grok-pi -- --model openai/gpt-4o

Requirements: Rust 1.92.0, Node.js 22.19.0 or newer, npm, and a system Pi installation.

./build.sh
./target/debug/grok-pi
# or: PI_BIN=pi ./run-local.sh

Project Cargo commands should go through ./scripts/cargo-shared.sh: incremental compilation is enabled by default, the generated target is capped at 128 GiB, and Cargo stops before free space falls below 20 GiB. Override the target cap with CARGO_TARGET_MAX_GIB; periodic maintenance clears incremental caches first and runs cargo clean if an already-over-cap target remains too large. Override CARGO_MIN_FREE_GIB only deliberately; set CARGO_MAINTENANCE=0 to skip one pre-command maintenance pass. The running disk guard continuously enforces the free-space floor; target-size maintenance runs on its configured cadence.

Run verification with:

./verify.sh

See VERIFICATION.md for the distinction between static checks and runtime acceptance.

• Feature matrix — supported behavior and intentional boundaries
• Subagents V2 guide — opt-in team collaboration, stable paths, presets, queue semantics, rollback, and troubleshooting
• Architecture alignment — component ownership, protocol mapping, and migration guidance
• Verification record — completed checks and known environment blockers
• Changelog / 更新日志 — release history (EN / ZH)
• Contributing — contribution guidelines

See LICENSE and THIRD-PARTY-NOTICES for project and upstream notices.

When a native grok-pi capability is on, the host resource policy may block known conflicting Pi packages so tool names / roles do not collide. Built-in defaults live in crates/codegen/xai-grok-pager/assets/native_feature_conflicts.toml. Runtime overlays (no rebuild): $GROK_HOME/native-feature-conflicts.toml, then $GROK_PROJECT_DIR/native-feature-conflicts.toml (package union; non-empty reason overwrites). User resource allow still wins.

flowchart LR
 A[Built-in defaults] --> M[Merge]
 B[User overlay] --> M
 C[Project overlay] --> M
 M --> T[Conflict table]
 T --> P[Block when feature on]

Eval bridge generations are mutually exclusive and selected at process start. Eval v1 remains the default. Eval Bridge v2 can expose JavaScript, Python, or both:

[ui]
pi_eval = "v2"
pi_eval_v2_language = "all" # "js" (default), "py", or "all"
pi_eval_v2_display_mode = "effects" # "effects" (default) or "legacy"

Use pi_eval = "v1" (or omit the key) for legacy Eval. Eval v1 keeps persistent Python and JavaScript kernels; Eval Bridge v2 uses isolated cells with explicit store/load persistence and the selected language set. Because pi_eval is a single version selector, v1 and v2 cannot run concurrently. pi_eval and pi_eval_v2_language are restart-required.

pi_eval_v2_display_mode is presentation-only and applies immediately: effects keeps Eval v2 orchestration source out of the normal transcript and presents its effects/results, while legacy restores source + result rendering. Change it from F2 → Agent → Eval v2 display, edit [ui].pi_eval_v2_display_mode, or use /eval-display [effects|legacy]; /eval-display with no argument toggles the current mode. The selected mode is persisted for future sessions.

Turning Pi subagents off omits the bundled bridge, forces PI_GROK_SUBAGENTS=0, and admits conflicting third-party packages again for the next process.

F2 descriptions for the opt-in rows append When on, blocks: ... from the same table.