πgrok-pi/Documentation
← HomeGitHub

Architecture

Composition, not a fork. Three boundaries. Pi source is not modified for the bridge. The adapter stays headless. Grok Pager is the only TUI.

The three layers

Grok Pager

Terminal lifecycle, input, rendering, dialogs, scrollback

  • Owns the terminal — init, restore, alternate screen, minimal mode
  • PromptWidget, slash completion, QuestionView, toasts, diffs
  • Native SessionPicker, model selector, SessionTree, Tasks Pane
  • F2 settings (external_only rows for Pi-only gates)
  • Upstream workflow engine surfaces when Pi workflows are enabled

pi-grok-adapter

Headless JSONL RPC ↔ ACP bridge

  • No terminal — no Ratatui, Crossterm, or raw-mode
  • Tool / stream / queue / session catalog projection
  • WorkflowHost, GoalHost, plan-mode tracker (adapter-owned state)
  • x.ai/* ACP methods for bash background, subagent, workflow, recap
  • Never invents a second TUI

Pi Agent Core

Agent loop, models, providers, tools, extensions, sessions

  • Always started in --mode rpc (system pi ≥ 0.99.0)
  • Local JSONL sessions; trust, settings, package lifecycle
  • Extension ecosystem + skills + prompts
  • Sub-agent child AgentSession; compaction; model providers
  • Source not modified for the bridge — inject via extension API

Runtime design (0.0.8)

Product isolation

Default homes: ~/.grok-pi and <repo>/.grok-pi. No dual-scan of stock ~/.grok. Pi agent state remains under ~/.pi/agent (or --session-dir).

Extension self-heal

Bootstrap failure → binary-search --extension list → name culprit → relaunch without it. Escape: grok-pi -ne.

Resource manager (Rust)

/pi-config two-pane UI reads Pi settings/trust; admission policy at spawn. Package install/remove stays on the Pi CLI.

Workflows & goal (opt-in)

F2 pi_workflows / pi_goal default off; restart injects extensions. Scripts under .grok-pi/workflows.

Field map: Feature matrix · Extensions · NATIVE_GROK_TUI_ALIGNMENT.md

Integration seams

ACP does not cover every Pi UI/command. Narrow Pager seams (illustrative — verify against current source-identity baseline):

UiProfile::ExternalDisables Grok.com product surfaces; keeps Pager renderer
AcpConnection::externalPager accepts an external ACP channel from the adapter
run_externalProduction terminal/event-loop without Grok Agent startup
UI notification handlersStatus → toast / banner / title / editor
QuestionView + Remote TUINative freeform + experimental ctx.ui.custom host
Slash profileRetained Grok commands + ACP catalog for Pi/dynamic
Plan / queue / tasksNative plan toggle, queue pane, background task cards
Session tree / jumpPi navigateTree + turn jump; not Grok destructive Rewind
Voice dictationNarrow Pager-owned /voice; does not own Pi models

Invariants

  • ✓ Grok Pager is the only visible TUI
  • ✓ Pi owns agent loop, sessions, models, extensions
  • ✓ adapter has no Ratatui / Crossterm / raw-mode
  • ✓ do not patch Pi source to extend RPC — extension API first
  • ✓ project trust is Pi-owned; Grok does not re-adjudicate