Extensions
grok-pi injects thin bridge extensions into Pi so native Grok surfaces can own Bash, sub-agents, context, recap, and more — without forking Pi. On top of that, install community packages the same way you would for interactive Pi.
Recommended community extensions
These are not bundled. Install once into your Pi agent home; both pi and grok-pi load them.
Structured questions → QuestionView
Recommended · Remote TUI pathnpm:@juicesharp/rpiv-ask-user-question
Lets the agent ask multi-option / multi-select questions mid-turn. Interactive Pi can open a custom factory UI; under grok-pi the stable path is Remote TUI (default on), which runs the factory in-process and projects onto native Grok QuestionView-style surfaces when the bridge can host it.
pi install npm:@juicesharp/rpiv-ask-user-question- Keep PI_GROK_REMOTE_TUI=1 (default) so third-party custom UI can run.
- Pure JSONL RPC without the custom host cannot serialize factory components — that is why Remote TUI exists.
- If a questionnaire declines, check Remote TUI is enabled and the extension is loaded (not blocked by policy).
# Recommended pair for grok-pi workflows
pi install npm:@juicesharp/rpiv-todo
pi install npm:@juicesharp/rpiv-ask-user-question
# Verify in resource manager
grok-pi
# then F2 or /pi-config → ExtensionsBundled: enhanced Bash
Owns every Bash child process so the Pager can promote a live foreground command into Grok’s native background-task UI without re-running it.
- Foreground bash reuses Pi createBashToolDefinition output/render semantics.
- Pager “Send to Background” transfers the same subprocess via x.ai/terminal/background (toolCallId control file).
- Native task cards: kill via x.ai/task/kill; agent tools get_task_output / wait_tasks / kill_task stay available.
- Supports is_background + description for model-started background shells.
PI_GROK_BASH=1 (default). Disable with PI_GROK_BASH=0 or --no-extensions.
What you see in the TUI
- Agent runs a long bash (build, test, install…).
- Use Pager's native Send to Background on the tool card — process keeps running; card becomes a task row.
- Kill, wait, or poll from the task UI or via agent tools (get_task_output, wait_tasks, kill_task).
Bundled: sub-agents
Spawns a real Pi child AgentSession and projects lifecycle into native SubagentBlock, Tasks Pane, and child AgentView.
- Profiles: general-purpose (all tools), explore / plan (safer tool sets).
- Capability modes: read-only, read-write, execute, all.
- Foreground or background (max concurrency 4 for background).
- Versioned bridge pi-grok-subagent/v1 → adapter → x.ai/subagent/* surfaces; cancel is first-class.
- Child sessions are persisted; parent resume can rebuild lifecycle from index entries.
Injected with other bridge extensions. Disabled under --no-extensions / -ne.
| Profile | Tools | Use when |
|---|---|---|
| general-purpose | read, bash, edit, write | Delegated implementation slices |
| explore | read, bash | Codebase investigation, diagnostics |
| plan | read, bash | Plans with risks + verification only |
Full bridge catalog
Source lives under extensions/ in the repo. Host injects them at spawn; they are not Pi core patches.
| Extension | Role | Default |
|---|---|---|
| pi-grok-bash | Bash ownership + background promote | On |
| pi-grok-subagents | Child AgentSession + native task UI | On |
| pi-grok-context | System/tools/AGENTS/skills breakdown for /context | On |
| pi-grok-recap | Display-only session recap (no history mutation) | On |
| pi-grok-auth | /login /logout via Remote TUI surfaces | On |
| pi-grok-export | /export-html and /pi-share (gist) | On |
| pi-grok-remote-tui | ctx.ui.custom host + frame projection | On* |
| pi-grok-rpc-compat | Present mode=tui to third-party extensions | With Remote TUI |
| pi-grok-plan-mode | Plan gate + exit_plan_mode approval | On |
| pi-grok-goal | /goal + update_goal (F2, restart) | Off (F2) |
| pi-grok-rollback | Tree file rollback snapshots | Off (F2) |
| pi-grok-tools | F2 built-in tool allow/deny preference | On |
| pi-grok-workflows | Pi spawn backend for Rhai workflows | Off (F2) |
| pi-grok-native-commands | Experimental /pi-* selectors | Off (env) |
* Remote TUI default-on; set PI_GROK_REMOTE_TUI=0 to disable. F2-gated features need a full process restart after toggle.
Recap, workflows, self-heal
Recap (/recap)
pi-grok-recap is display-only — does not rewrite session history. Auto when away ≥3 min (and ≥3 turns). Optional Mermaid via F2 recap_mermaid. Configure recap_model in F2 (never silently falls back to the live session model).
Rhai workflows
F2 → Pi workflows (default off, restart). Scripts under ~/.grok-pi/workflows and <repo>/.grok-pi/workflows. Slash: /workflow, /workflows, /create-workflow. Host uses upstream xai-workflow with a Pi spawn backend; __pi_workflow_* bridge cmds are hidden from the catalog.
Self-heal on bad extensions
If any injected or discovered extension kills RPC bootstrap, the host binary-searches --extension paths, prints the culprit, and relaunches without it. Manual: grok-pi -ne.
Enable / disable
# Disable all injected bridge extensions
grok-pi -ne
# or
grok-pi --no-extensions
# Bash only
PI_GROK_BASH=0 grok-pi
# Remote TUI (custom UI host for packages like rpiv-ask)
PI_GROK_REMOTE_TUI=0 grok-pi # off
PI_GROK_REMOTE_TUI=1 grok-pi # on (default)User / project extensions still load through Pi discovery (~/.pi/agent, trusted project trees) unless blocked by /pi-config policy.
FAQ
Do I need to install pi-grok-bash myself?
No. The composition binary injects it at runtime. Built-in Todo is also injected by default; install only community packages you still want, such as ask-user-question.
Why have Todo if the host already has plan mode?
Plan mode is a write gate + approval flow. Built-in Todo is the living checklist projected into TodoPane — complementary, not a replacement. F2 pi_todo is on by default; when it is on grok-pi blocks rpiv-todo to avoid duplicate tool registration. Turn pi_todo off and restart if you intentionally want the community provider instead.
Will ask-user-question work without Remote TUI?
Not reliably. The package depends on in-process custom UI. Keep Remote TUI on (default) for questionnaires.
Can I still use arbitrary Pi extensions?
Yes. Install with pi install … or drop packages under Pi extension paths; manage visibility in F2 / /pi-config.