pi-xai

---

Direction

Today: Grok Build provider path for Pi (subscription cli-chat-proxy, OAuth, model catalog, payload/header parity with open-source Grok Build).

Soon: when Pi ships native Grok, the provider + OAuth layer here is transitional and can shrink. This package stays a Grok / xAI flavor pack: tools and QoL that core Pi will not own.

Lives in pi-xai	Use other extensions (below)
Protocol, catalog, agentic xAI tools	Task / subagent harness → pi-subagents
Imagine / video / web_fetch	Live todos → pi-tasks
/goal, /plan, prompt ghost, /xai-usage	Recurring prompts (/loop-like) → pi-schedule-prompt
Composer vision routing	MCP bridges → pi-mcp-adapter
Voice / TTS / STT	pi-xai-voice

Requires Pi ≥ 0.80. Docs: xAI Responses.

---

Quick start

pi install npm:pi-xai

/login grok-build
/model grok-build/grok-4.5

Command	What it does
/login grok-build	OAuth (web / device / import grok login)
/model grok-build/…	Catalog below
/goal <objective>	Goal mode (status / pause / resume / clear) + tool update_goal
/plan	Plan mode (on / off / status / show); tools enter_plan_mode / exit_plan_mode
/imagine	Image gen — prompt passed verbatim to image_gen
/imagine-video	Video workflow (image_gen → image_to_video)
/xai-suggest	Next-prompt ghost (on / off / clear); Tab commits
/xai-usage	Monthly/weekly subscription bars (% left) + reset
/xai-usage statusbar	Footer Grok 40% left · 3d 12h (Grok models only)
/xai-vision:status	Vision routing for text-only models (Composer default)

Live X posts: agentic x_search or tool xai_x_search — not Pi’s x_semantic_search / x_keyword_search.

---

Companion extensions (Grok-like features we don’t reimplement)

Stack these next to pi-xai when you want a fuller Grok Build feel without bloating this package:

Grok-ish need	Extension	Notes
Subagents / parallel tasks	edxeth/pi-subagents	Replaces snacking Grok task / wait_tasks / kill-task harness
Structured todos / progress UI	edxeth/pi-tasks	Replaces snacking Grok todo_write
Recurring / scheduled prompts	tintinweb/pi-schedule-prompt	Replaces snacking Grok /loop + scheduler_*
MCP servers as tools	nicobailon/pi-mcp-adapter	Private APIs, extra tools Grok might cover via MCP
Voice / dictation / TTS	luxus/pi-xai-voice	Sibling; uses pi-xai OAuth when present
Full Imagine studio / extra media	luxus/pi-xai-imagine	Dual-install: video tools auto-skip here if imagine is loaded

Example ~/.pi/agent/settings.json packages list:

{
  "packages": [
    "npm:pi-xai",
    "github:luxus/pi-xai-voice",
    "github:edxeth/pi-subagents",
    "github:edxeth/pi-tasks",
    "github:tintinweb/pi-schedule-prompt",
    "github:nicobailon/pi-mcp-adapter"
  ]
}

(Paths like ../../projects/pi-xai work for local checkouts.)

---

Aligned with Grok Build

• Default base: https://cli-chat-proxy.grok.com/v1
• Client 0.2.101 / grok-shell headers + dynamic x-grok-conv-id
• include: reasoning.encrypted_content on reasoning models (proxy + public API)
• Official tool names: image_gen, image_edit, image_to_video, web_fetch, plan/goal tools
• No Cursor capital shims (Grep/Glob/WebSearch) — Pi natives + server web_search
• CLI import keeps refresh_token from ~/.grok/auth.json

Public API override:

// ~/.pi/agent/settings.json
{
  "xai": {
    "baseUrl": "https://api.x.ai/v1"
  }
}

	CLI proxy (default)	Public API
Base	cli-chat-proxy.grok.com/v1	api.x.ai/v1
Auth	/login grok-build	OAuth or XAI_API_KEY
Encrypted reasoning	yes (CLI headers)	yes
Media tools	often use api.x.ai when proxy lacks routes	same

---

Models

ID	Context	Input	Role
grok-composer-2.5-fast	200K	text	Fast coding; vision routing on by default
grok-build	500K	text + image	Coding
grok-4.5	500K	text + image	Flagship reasoning
grok-4.3	1M	text + image	Long context
grok-4.20-0309-reasoning	2M	text + image	Auto reasoning
grok-4.20-0309-non-reasoning	2M	text + image	Fast 4.20
grok-4.20-multi-agent-0309	2M	text + image	Multi-agent research

Pi cost numbers are per-token UI estimates. Real subscription allowance: /xai-usage.

---

Features

Goal mode

/goal ship the feature end-to-end
/goal status | pause | resume | clear

Tool update_goal: message | completed | blocked_reason. Lean (no classifier harness).

Plan mode

/plan          # toggle
/plan on|off|status|show

Tools enter_plan_mode / exit_plan_mode. Plan file .pi/plan.md. While on: no edit/write; bash allowlist.

Prompt ghost (next message)

After each turn, predicts the next user prompt (default model grok-composer-2.5-fast). Dim text in the empty textbox; Tab commits; Enter sends (ANSI stripped).

/xai-suggest on|off|status|clear

XAI_PROMPT_SUGGESTIONS=0 or /xai-suggest off disables. Model override: XAI_PROMPT_SUGGESTIONS_MODEL.

Imagine & video

Tool / cmd	Purpose
/imagine	Slash → image_gen with prompt verbatim
image_gen	Text → image
image_edit	Edit (paths → data URIs)
/imagine-video	Single-clip workflow
image_to_video	Animate one image (duration 6 or 10s)

{ "xai": { "text": { "imageGen": false, "videoGen": false } } }

Video tools auto-skip when pi-xai-imagine is in your packages list.

web_fetch

Client fetch of a public URL → markdown/text. HTTPS upgrade, SSRF blocks (localhost / private / metadata), size + char caps. Not for authenticated private sites.

Agentic server tools (default on)

{
  "xai": {
    "text": {
      "agentic": true,
      "agenticTools": ["web_search", "x_search", "code_interpreter"]
    }
  }
}

Responses tools

Tool	Purpose
xai_generate_text	Full Responses API
xai_x_search	Native X search
xai_multi_agent	Multi-agent research (default on; 4.20 multi-agent)

{ "xai": { "text": { "multiAgent": false } } }

Usage QoL

/xai-usage
/xai-usage statusbar

Needs Grok Build OAuth. Web: grok.com usage.

{ "xai": { "text": { "usageStatus": true } } }

Vision routing (Composer)

Default composer: images from read → describe via grok-4.5 → text.

/xai-vision:composer | on | off | status | cache-clear

Config: ~/.pi/xai-vision.json

Provider behavior (while present)

1. Strip OpenAI-only fields xAI rejects
2. Merge server built-ins with Pi tools
3. Normalize empty content; system → instructions
4. Local image paths → data URIs
5. prompt_cache_key (session)
6. Request encrypted reasoning include
7. CLI proxy headers + conv-id

---

Development

npm install
npm run check
npm test
npm run verify:deps

File	Role
index.ts	Entry, tools, hooks
xai-provider.ts	Catalog + provider (transitional)
xai-oauth.ts	OAuth + /xai-usage (transitional core)
xai-config.ts	Settings + dual-install detection
xai-stream.ts	CLI proxy headers
xai-images.ts	Image path → data URI
xai-image-gen.ts	image_gen / image_edit + /imagine
xai-video-gen.ts	image_to_video + /imagine-video
xai-web-fetch.ts	web_fetch
xai-goal.ts	/goal + update_goal
xai-plan-mode.ts	/plan + enter/exit_plan_mode
xai-prompt-suggest.ts	Next-prompt ghost
xai-vision.ts	Text-only vision routing
xai-usage-status.ts	Footer quota

See CHANGELOG.md.

---

License

MIT