Configuration

Env vars, CLI flags, F2 feature gates, and product-isolated state trees. Stable bridges default on; experimental surfaces are opt-in.

Product state isolation

grok-pi does not share stock Grok's config roots by default:

Layer	stock Grok	grok-pi default
User home	~/.grok	~/.grok-pi
Project tree	<repo>/.grok	<repo>/.grok-pi

Pi agent state stays under ~/.pi/agent (or --session-dir). No dual-scan of stock trees. Migrate UI prefs with:

migrate-home

grok-pi migrate-home --status
grok-pi migrate-home --dry-run
grok-pi migrate-home          # copy allowlisted files
grok-pi migrate-home --include-auth   # optional

Empty target + legacy data → one-shot auto-migrate with .migrated-from-legacy marker. Workflows are not auto-copied; place Rhai scripts under ~/.grok-pi/workflows or <repo>/.grok-pi/workflows.

Environment variables

Variable	Default	Purpose
GROK_HOME	~/.grok-pi	User state root (isolated from stock Grok ~/.grok)
GROK_PROJECT_DIR	.grok-pi	Project config/workflows/hooks dirname under the repo
GROK_LEGACY_HOME	~/.grok	Source tree for migrate-home / auto-migrate
PI_GROK_REMOTE_TUI	1	Host Pi ctx.ui.custom through Grok Pager (Remote TUI)
PI_GROK_BASH	1	Grok-owned Bash + Send to Background
PI_GROK_NATIVE_COMMANDS	0	Experimental /pi-* native selectors
PI_GROK_EXCLUDE_TOOLS	unset	Comma-separated built-in tools to exclude
GROK_PI_NO_AUTO_UPDATE	unset	Disable background GitHub update checks
GROK_PI_INSTALL_DIR	~/.local/bin	Custom install path for install.sh
PI_BIN	pi	Pi binary used by the host
PI_CODING_AGENT_SESSION_DIR	Pi default	Override Pi session root (same as Pi)

CLI flags & subcommands

First-class Pi flags are forwarded by the host. Extra args after -- still pass through.

Pass Pi flags

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

Flag	Description
--pi-cwd <path>	Project directory for the Pi child
--pi-bin <path>	Pi executable path
--continue / -c	Continue the previous session (skips Welcome)
--session <id>	Resume session (partial UUID OK)
--session-dir <path>	Custom Pi session directory
--fork	Fork semantics at startup (Pi flag)
--no-session	Do not open/persist a session file
--name <name>	Name the session
--provider / --model	Provider and model selection
--thinking <level>	Thinking effort
--system-prompt / --append-system-prompt	Prompt overrides
--extension <path>	Extra Pi extension paths
--no-extensions / -ne	Disable injected bridge + user extensions
--no-skills / --no-context-files	Disable Pi skill / AGENTS discovery
--tools / --exclude-tools / --no-tools / -nt	Tool allow/deny lists
--no-builtin-tools / -nbt	Drop Pi built-in tools
--approve / --no-approve	Trust / approval gates
--offline	Disable network where Pi honors it
migrate-home	CLI subcommand: copy allowlisted files from legacy ~/.grok
update [--check]	Install or check GitHub Releases

F2 feature gates

Open F2 (settings). Pi-only rows are external_only — hidden unless you are on the grok-pi / external profile.

Setting	Default	Notes
[ui].pi_workflows	off	Rhai workflows (/workflow…); restart required
[ui].pi_goal	off	Goal mode MVP (/goal); restart required
[ui].pi_tree_file_rollback	off	SessionTree r/R file rollback; restart
recap_mermaid	off	Render Mermaid in /recap bodies
remote_tui_footer	varies	Remote TUI footer lab surface

Pi resource manager

/pi-config (alias /pi-resources) or F2 → Pi resources opens a Rust-native two-pane manager: extensions, skills, prompts, themes across global and trusted-project scopes. Reads Pi settings.json / trust.json. Does not run pi install/remove/update — use the Pi CLI for package lifecycle, then refresh or /reload.

Filters: All / Enabled / Disabled; policy view (a); refresh (r); Tab = scope
Source identities: GitHub / npm / local paths (not generic tags)
Admission policy can block noisy sources (e.g. custom header/footer, pi-tool-display)

Extension self-heal

If a Pi extension crashes RPC bootstrap, grok-pi runs a VS Code-style binary search over --extension paths, names the culprit, and relaunches without it so you are not stuck. Escape hatch: grok-pi -ne.

Themes

/theme pi:<name> maps Pi theme JSON into Grok Theme. Built-ins for terminal opacity:

pi:transparent — dark
pi:transparent-light — light