Migration

Two entry paths, one host: keep Grok muscle memory or keep Pi sessions — grok-pi sits between Grok Pager and Pi agent core.

From stock Grok Build

Same terminal, same shortcuts — agent runtime becomes Pi.

Install grok-pi

One command. The installer detects your platform and installs the binary to ~/.local/bin.

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

Ensure Pi ≥ 0.99.0

grok-pi drives Pi as its agent core and requires the built-in MCP/Codemode baseline. Install or update Pi via npm.

npm install --global @earendil-works/pi-coding-agent

Run in your project

cd into your project and go. Grok Pager keybindings and themes still apply; agent power comes from Pi.

cd your-project && grok-pi

From interactive Pi

Keep Pi sessions, models, and extensions. Swap the front-end for Grok Pager.

Install grok-pi (keep Pi)

You already have Pi. Add the host binary only — sessions, models, and ~/.pi/agent stay where they are.

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

Run grok-pi instead of pi

Same project cwd. Same Pi session store. Different TUI (Grok Pager) in front of the same agent core.

cd your-project && grok-pi

Resume existing sessions

Partial UUID works, same as Pi --session. Or use /resume inside the TUI.

grok-pi --session 019f88c
grok-pi --continue

What you keep

Sessions stay on Pi

JSONL under ~/.pi/agent/sessions (or --session-dir / PI_CODING_AGENT_SESSION_DIR). No import step. /resume lists the same catalog.

Models, tools, extensions

Pi providers, tools, skills, prompts, and extensions keep loading from Pi paths. grok-pi injects only bridge extensions for the Pager surface.

Settings still apply

Pi settings.json and auth remain authoritative for the agent. UI chrome (F2, themes display) lives under ~/.grok-pi — isolated from stock Grok.

Quit → resume command

On exit you get: To resume this session: grok-pi --session <uuid> — same idea as interactive pi, host binary name swapped.

What changes

TUI is Grok Pager

No Pi interactive TUI. Slash completion, tool cards, diffs, and modals are native Grok surfaces mapped to Pi RPC.

Some Pi-only pickers change

/model and /resume use Grok SessionPicker / model UI, not Pi’s TUI components. Behavior is equivalent; layout may differ.

Product state dirs

UI prefs/workflows default to ~/.grok-pi and <repo>/.grok-pi so they never collide with stock Grok ~/.grok. Pi agent state is unchanged.

Always RPC mode

grok-pi always starts Pi with --mode rpc. Do not expect interactive-only Pi widgets that require an in-process TUI factory.

UI home: stock Grok → ~/.grok-pi

From 0.0.8, user chrome defaults to ~/.grok-pi so it never collides with stock Grok. Pi sessions stay under ~/.pi/agent. Optional one-shot copy of allowlisted files:

migrate-home

grok-pi migrate-home --status
grok-pi migrate-home --dry-run
grok-pi migrate-home

Empty target + legacy data may auto-migrate once. Workflows are not copied; put Rhai scripts in ~/.grok-pi/workflows or <repo>/.grok-pi/workflows after enabling F2 Pi workflows.

Why switch?

Keep your Grok muscle memory

Same Pager, same slash commands, same Ctrl+key shortcuts. grok-pi adds capability, not complexity.

Unlock any model

/model opens Pi’s full catalog — GPT-4o, Claude, Gemini, local LLMs, custom endpoints. Switch mid-session.

Own your sessions

Local JSONL files. Fork, clone, tag, recap. No cloud dependency.

Full extension ecosystem

Pi extensions, skills, and prompts appear as native Grok slash commands.

Sub-agents & parallel work

Pi sub-agents project into native SubagentBlock, Tasks Pane, and child AgentView.

Context visibility

Click the context bar or run /context for a live breakdown of tokens.

FAQ

Do I lose any Grok Build features?

grok-pi retains Grok Pager rendering, input, and navigation. Grok product-only surfaces (cloud history, usage, plugins) are replaced by Pi equivalents — local sessions, extensions, full model access.

Can I keep using interactive pi?

Yes. grok-pi is a separate binary. Run pi for Pi’s TUI, grok-pi for Grok Pager + Pi core. Sessions are shared when they use the same session dir.

Can I go back to stock Grok Build?

Yes. stock grok is untouched. Run grok for the original product; grok-pi for the bridged host.

Does grok-pi modify Pi or Grok source?

No. Pi source is not modified for the bridge. Grok renderer identity is guarded; the adapter is a headless JSONL RPC ↔ ACP bridge.

What about my existing Pi sessions?

They work as-is. grok-pi reads Pi JSONL directly. /resume shows the catalog; --session <uuid> reopens a specific one.