{"id":50814609,"url":"https://github.com/luxus/pi-xai","last_synced_at":"2026-06-13T08:06:03.976Z","repository":{"id":358347519,"uuid":"1240938433","full_name":"luxus/pi-xai","owner":"luxus","description":"Pi extension for xAI Grok Build (Coding Plan)","archived":false,"fork":false,"pushed_at":"2026-05-16T22:05:11.000Z","size":130,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T00:22:02.386Z","etag":null,"topics":["grok","llm","multi-agent","pi","responses-api","typescript","xai"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luxus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-16T18:59:52.000Z","updated_at":"2026-05-16T22:05:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/luxus/pi-xai","commit_stats":null,"previous_names":["luxus/pi-xai"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/luxus/pi-xai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luxus%2Fpi-xai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luxus%2Fpi-xai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luxus%2Fpi-xai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luxus%2Fpi-xai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luxus","download_url":"https://codeload.github.com/luxus/pi-xai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luxus%2Fpi-xai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34276573,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grok","llm","multi-agent","pi","responses-api","typescript","xai"],"created_at":"2026-06-13T08:06:03.326Z","updated_at":"2026-06-13T08:06:03.964Z","avatar_url":"https://github.com/luxus.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pi-xai\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/pi-xai-logo.png\" width=\"320\" alt=\"pi-xai\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/pi-xai\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/pi-xai.svg?style=flat-square\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/luxus/pi-xai\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/luxus/pi-xai?style=flat-square\" alt=\"GitHub Stars\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nPi extension for xAI Grok Build — Responses API, native OAuth, 5 tools + automatic agentic mode.\n\n**Note:** Full access to Grok Build requires a **SuperGrok Heavy** subscription (see below).\n\n## Features\n\n- **grok-build provider** — `/login grok-build` (native Web PKCE OAuth recommended with browser + manual-paste fallback, or Device Code for headless; no binary), Responses API (`openai-responses`), full reasoning\n- `xai_generate_text` — stateful conversations, structured JSON output, built-in tools (with advanced filters), `reasoningEffort`, `previousResponseId`, custom timeout\n- `xai_multi_agent` — 4/16-agent research (`reasoningEffort`), live progress updates via `onUpdate`\n- **Agentic mode** — when any `grok-*` model is active, the extension auto-injects web_search / x_search / code_execution; the model decides what to call (the \"magic\")\n- Full OAuth implementation: Web PKCE (OIDC discovery, PKCE, callback server with CORS + manual input) + Device Code fallback, JWT expiry + per-key refresh lock, improved ~/.grok/auth.json parsing (canonical + legacy), optional import from Grok CLI\n\nModels (via `/model grok-build/...`): `grok-build` (primary Coding Plan alias), `grok-4.3`, `grok-4.3-latest`.\n\nEverything works with Grok Build OAuth or plain `XAI_API_KEY`.\n\n## Getting Grok Build Access\n\nThe `grok-build` provider and model require a **SuperGrok Heavy** subscription.\n\n- SuperGrok has a free 3-day trial.\n- When upgrading from SuperGrok, look for the limited offer to get **SuperGrok Heavy** for $99/month for the first 6 months.\n\n![SuperGrok Heavy offer](assets/supergrok-heavy-offer.png)\n\n## Quick start\n\n```bash\npi install npm:pi-xai\n# then in Pi:\n/login grok-build\n/model grok-build/grok-build\n```\n\nAsk anything. Agentic mode handles research for you, or call any of the five explicit tools (`xai_generate_text`, `xai_multi_agent`, `xai_web_search`, `xai_x_search`, `xai_code_execution`) for precise/direct control.\n\n## Tools\n\n| Tool                 | Description                                                      |\n| -------------------- | ---------------------------------------------------------------- |\n| `xai_generate_text`  | Responses API text gen with reasoning, JSON schema, tools, state |\n| `xai_multi_agent`    | Deep research (4 or 16 agents), progress, multi-turn             |\n| `xai_web_search`     | Web search via Grok (prompt simulation for current knowledge)    |\n| `xai_x_search`       | X/Twitter search via Grok (prompt simulation)                    |\n| `xai_code_execution` | Python code analysis/execution simulation via Grok               |\n\n## Agentic mode config (optional)\n\n`~/.pi/agent/settings.json` (or `.pi/settings.json`):\n\n```json\n{\n  \"xai\": {\n    \"text\": {\n      \"agentic\": true,\n      \"agenticTools\": [\"web_search\", \"x_search\"]\n    }\n  }\n}\n```\n\nDefault = enabled with all three built-in tools.\n\n## Payload normalization modes (`compatible` vs `aggressive`)\n\nThe extension supports two payload normalization modes for grok-* models (via the `openai-responses` driver + our hook). Controlled by `xai.payloadMode` in `~/.pi/agent/settings.json` (or project `.pi/settings.json`):\n\n```json\n{\n  \"xai\": {\n    \"payloadMode\": \"compatible\"   // default — or \"aggressive\"\n  }\n}\n```\n\n### `compatible` (default)\n- 100% unchanged behavior for existing users.\n- Applies a defensive, enhanced content-element normalizer (catches `content: []`, `\"\"`, whitespace-only, arrays of only malformed/empty/garbage parts, while safely preserving pure `input_image` vision messages and mixed content).\n- Protects against the common 400 \"Each message must have at least one content element\" after tool turns or certain histories.\n- Sufficient for the majority of users and the rich `xai_*` tools.\n\n### `aggressive`\n- **Opt-in only** (no default change ever).\n- Runs the full rewrite in the provider chat/agentic path (`before_provider_request` for grok-*):\n  - The complete `normalizeForXai` (content guarantee + **Hermes-like reasoning-item stripping**).\n  - Relocates developer/system messages to top-level `instructions`.\n  - Stricter `function_call_output.output` sanitization (arrays → text with `[image]` placeholders + JSON fallback to avoid 422s).\n- **Hermes parity (substantially)**: The aggressive path now brings over the highest-impact anti-400 patterns from the 2026-05-19 exploration of the Hermes agent clone (`/tmp/hermes-agent-clone`):\n  - Proactive stripping of every `type: \"reasoning\"` item in `input` (directly ports the `is_xai_responses=True` logic in `codex_responses_adapter.py:_chat_messages_to_responses_input` that skips replay of `codex_reasoning_items` / encrypted_content for xAI, plus the transport's `include:[]` behavior).\n  - Eliminates \"reasoning without following content item\" (`missing_following_item`) and replay of encrypted blobs that xAI OAuth/SuperGrok rejects.\n  - Post-strip content fix ensures any leftover pure-reasoning follower assistants are valid `[{type:\"output_text\", text:\"\"}]`.\n  - Matches the exact root cause of recurring 400s on high-reasoning (grok-4.3), long tool-using sessions, and news-search follow-ups that survived prior compatible hardening.\n- Sibling extensions and direct `/responses` callers get the full benefit by calling the exported `normalizeForXai(inputArray)` helper (see JSDoc in `index.ts` for the exact usage recipe).\n\n**When to switch to `aggressive`**:\n- You hit 400s on complex/high-reasoning/tool-heavy conversations despite the default.\n- Developing or using sibling packages (`pi-xai-imagine`, etc.) that do direct Responses calls.\n- Long multi-turn agentic workflows or \"imagine\" workspaces with heavy reasoning.\n- You want the closest experience to how Hermes (the reference) handles xAI paths.\n\n**Important limitations** (transparent due to architectural constraints):\n- The rich built-in tools (`xai_generate_text`, `xai_web_search`, `xai_x_search`, `xai_code_execution`, `xai_multi_agent`) and any code path that goes through the internal `callXaiResponses` (including many sibling direct calls during development) **always use only the enhanced-compatible normalization**, even if you set `payloadMode: \"aggressive\"`. They never receive the reasoning strip, relocation, or extra tool cleaning.\n- For full aggressive/Hermes guarantees on *your own* direct Responses calls, explicitly call `normalizeForXai(...)` on the `input` array (the helper is the single source of truth and the recommended path for power users / siblings).\n- Only the normal provider-driven grok-* chat + auto-injected agentic tools path gets the complete aggressive treatment.\n\nSee the detailed JSDoc on `normalizeForXai` and the payloadMode block in `index.ts` for implementation notes, every `(as any)` rationale, and the full constraint history (smallest possible diff, no new internal helpers, single grok-build provider, in-place only).\n\n## Development\n\nZero-config modern stack (oxfmt default, oxlint zero-config, tsgo only):\n\n```bash\nnpm install\nnpm run check      # tsgo --noEmit\nnpm run lint       # oxlint .\nnpm run format     # oxfmt --write .\nnpm test\n```\n\nHusky + lint-staged runs `oxfmt --write`, `oxlint`, `tsgo --noEmit` on every commit.\n\nExactly 4 source files. See CHANGELOG.md.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluxus%2Fpi-xai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluxus%2Fpi-xai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluxus%2Fpi-xai/lists"}