docs(providers): add dedicated xAI / Grok provider guide#66
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces comprehensive documentation across multiple languages (English, Japanese, Korean, and Chinese) for routing Claude Code to xAI's Grok models using the new grok (subscription-based) and xai (API key-based) providers. The documentation covers setup, configuration, model routing, reasoning effort, and troubleshooting. A review comment correctly identifies an issue in the English guide where an executable shell command example uses angle-bracket placeholders (<your-slug's real window>), which could be misinterpreted by the shell as input-redirection operators; it is recommended to use quoted shell variables instead.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
No issues found across 13 files
Architecture diagram
sequenceDiagram
participant User as Claude Code User
participant CLI as shunt CLI
participant Auth as xAI Auth Service
participant File as ~/.shunt/xai-auth.json
participant GW as shunt Gateway
participant xAI as xAI Backend
Note over User,xAI: NEW: xAI/Grok Provider Flow
User->>CLI: shunt login xai
CLI->>Auth: Device code login (RFC 8628)
Auth-->>CLI: Tokens
CLI->>File: Write tokens (0600 perm)
File-->>CLI: Stored
Note over User,GW: Runtime Gateway Flow
User->>GW: Claude Code request (Anthropic Messages)
alt Grok Subscription Path (provider = "grok")
GW->>File: Read OAuth tokens from ~/.shunt/xai-auth.json
GW->>GW: Add Grok CLI headers (x-xai-token-auth, x-grok-client-identifier, x-grok-client-version)
GW->>GW: Transform Messages -> xAI Responses API
opt Reasoning effort configured
GW->>GW: Inject reasoning.effort field (opt-in only)
end
GW->>xAI: POST /v1/responses to cli-chat-proxy.grok.com
xAI-->>GW: Streamed response
GW-->>User: Translated Anthropic Messages response
else xAI Developer API Path (provider = "xai")
GW->>GW: Read XAI_API_KEY from environment
GW->>GW: Transform Messages -> xAI Responses API
opt Reasoning effort configured
GW->>GW: Inject reasoning.effort field (opt-in only)
end
GW->>xAI: POST /v1/responses to api.x.ai with Bearer token
xAI-->>GW: Streamed response
GW-->>User: Translated Anthropic Messages response
end
Note over GW,xAI: NEW: Web Search Not Available
alt Error Cases
xAI-->>GW: 402 Payment Required (subscription on API key path, or no credits)
xAI-->>GW: 403 Not Authorized (subscription tier gate)
xAI-->>GW: 400 on reasoning.effort (unsupported model)
end
|
/gemini review |
There was a problem hiding this comment.
Code Review
본 풀요청(PR)은 SuperGrok 구독 또는 xAI 개발자 API를 통해 Claude Code 추론을 xAI의 Grok 모델로 라우팅할 수 있도록 지원하는 문서 및 구성 업데이트를 추가합니다. 이를 위해 xAI/Grok 전용 가이드 문서를 신설하고, 프로바이더 및 구성 참조 문서를 업데이트하였으며, 일본어, 한국어, 중국어 번역본을 함께 제공합니다. 리뷰어는 한국어 번역 가이드 문서(site/src/content/docs/ko/guides/xai.md) 내의 여러 설정 예시 및 셸 스크립트 코드 블록에 남아 있는 영어 주석과 섹션 참조 링크를 한국어로 번역하여 일관성과 가독성을 높이도록 개선을 제안했습니다.
Greptile SummaryThis docs-only PR adds a dedicated xAI / Grok provider guide (
Confidence Score: 5/5Docs-only change with no Rust source modifications; safe to merge. All fourteen changed files are Markdown/MJS documentation. The new xai.md guide accurately describes both credential paths (verified against the implementation details in PR #58). Configuration reference fixes are consistent across all four locales. Internal locale-prefixed links are correctly formed throughout. No logic, configuration, or binary behavior is altered. No files require special attention. The README gap from a previous review thread was already addressed in commit a903d17. Important Files Changed
Sequence Diagram%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant CC as Claude Code
participant S as shunt
participant G as grok proxy<br/>(cli-chat-proxy.grok.com/v1)
participant X as xai API<br/>(api.x.ai/v1)
CC->>S: Anthropic Messages request
alt grok provider (xai_oauth)
S->>S: translate to Responses API + add Grok CLI identity headers
S->>G: POST /v1/responses Bearer xai-auth.json token
G-->>S: streamed Responses reply
else xai provider (api_key)
S->>S: translate to Responses API
S->>X: POST /v1/responses Bearer XAI_API_KEY
X-->>S: streamed Responses reply
end
S-->>CC: translated Anthropic Messages reply
%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant CC as Claude Code
participant S as shunt
participant G as grok proxy<br/>(cli-chat-proxy.grok.com/v1)
participant X as xai API<br/>(api.x.ai/v1)
CC->>S: Anthropic Messages request
alt grok provider (xai_oauth)
S->>S: translate to Responses API + add Grok CLI identity headers
S->>G: POST /v1/responses Bearer xai-auth.json token
G-->>S: streamed Responses reply
else xai provider (api_key)
S->>S: translate to Responses API
S->>X: POST /v1/responses Bearer XAI_API_KEY
X-->>S: streamed Responses reply
end
S-->>CC: translated Anthropic Messages reply
Reviews (7): Last reviewed commit: "docs(xai): use a concrete context-window..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request adds support and documentation for routing Claude Code inference to xAI's Grok models, supporting both the SuperGrok subscription (via OAuth) and the developer API (via API key). It includes comprehensive guides in English, Japanese, and Korean. The review feedback highlights several translation gaps in the Japanese guide, such as untranslated English link texts and code block comments, as well as inconsistent anchor links. It also recommends using quoted shell variables instead of raw placeholders in shell command examples to comply with the style guide.
|
/gemini review |
Rephrase the token-write sentence across all four locales so 0600 reads as a chmod permission on ~/.shunt/xai-auth.json rather than the token payload. Per gemini-code-assist review on PR #66.
|
/gemini review |
There was a problem hiding this comment.
Code Review
이번 풀리퀘스트는 xAI의 Grok 모델을 지원하기 위해 grok 및 xai 프로바이더에 대한 다국어(영어, 한국어, 일본어, 중국어) 가이드 문서와 설정 레퍼런스를 추가하고 관련 설정을 업데이트합니다. 리뷰 과정에서 실행 가능한 셸 명령 예시 내 플레이스홀더(YOUR_WINDOW)가 그대로 복사되어 실행될 때 오류를 유발할 수 있으므로, 이를 따옴표로 감싼 셸 변수("$MAX_TOKENS")로 개선하도록 권장하는 피드백이 제시되었습니다.
…lder Replace the YOUR_WINDOW placeholder in the CLAUDE_CODE_MAX_CONTEXT_TOKENS example with a concrete grok-4-family integer (256000), matching the house convention in codex.md / effort-and-context.md and keeping the 'set your slug's real window' comment. Copy-paste-safe and avoids an undefined shell var. Per gemini-code-assist review on PR #66.
|
/gemini review |
Add a standalone xai.md guide (en/ko/ja/zh-cn) covering the Grok subscription-OAuth provider, link it from the sidebar, and reference xai/grok as a built-in provider in providers.md and configuration.md across all four locales.
… typo - Localized xai.md cross-page anchors used English slugs that don't resolve against translated headings; point them at the real localized anchor IDs (verified from the built HTML). - Drop the false 'model discovery exposes grok-4.5/grok-4.3' claim (config seeds an empty model catalog; discovery only surfaces claude-named aliases) — it also self-contradicted the next paragraph. All 4 locales. - Troubleshooting row referenced $XAI_AUTH_FILE; the real override env var is $SHUNT_XAI_AUTH_FILE. All 4 locales.
…lder Angle brackets in the CLAUDE_CODE_MAX_CONTEXT_TOKENS example could be parsed as shell input-redirection when copy-pasted. Use an all-caps placeholder token instead. All 4 locales.
- README.md: add xai/grok rows to the built-in provider table and mention them in the intro (AGENTS.md requires README updated with provider changes). - ko/guides/xai.md: translate code-block comments to Korean to match the ko/codex.md convention (zh-cn was already translated; ja keeps English comments per ja/codex.md convention).
Bring ja/guides/xai.md to parity with ko/zh-cn: translate cross-page link texts to the official ja sidebar titles (Effort とコンテキスト / モデルディスカバリー / プロバイダー) and translate all code-block comments to Japanese. Kept the anchors that actually resolve (#reasoning-エフォート, not the non-existent #推論エフォート) and the YOUR_WINDOW placeholder for cross-locale consistency.
Rephrase the token-write sentence across all four locales so 0600 reads as a chmod permission on ~/.shunt/xai-auth.json rather than the token payload. Per gemini-code-assist review on PR #66.
…lder Replace the YOUR_WINDOW placeholder in the CLAUDE_CODE_MAX_CONTEXT_TOKENS example with a concrete grok-4-family integer (256000), matching the house convention in codex.md / effort-and-context.md and keeping the 'set your slug's real window' comment. Copy-paste-safe and avoids an undefined shell var. Per gemini-code-assist review on PR #66.
amondnet
force-pushed
the
amondnet/provider-docs
branch
from
03b0866 to
bd1ff28
Compare
|
1 participant
Summary
Docs-only change to the Astro Starlight site under
site/. Adds a dedicated per-provider guide for the xAI-family providers merged in #58 (grokandxai), links it from the providers overview, and corrects a couple of stale reference-doc gaps that predate this PR.Changes
guides/xai.mdin all 4 locales (en, ko, ja, zh-cn), matching the existingcodex.mddepth. Documents both:grok— SuperGrok / X Premium+ subscription OAuth viashunt login xai, backendcli-chat-proxy.grok.comxai— API key (XAI_API_KEY), backendapi.x.aiguides/providers.md(all 4 locales): addedxai+grokto the built-in providers table, added a Grok section linking the new page, de-staled the shunt-xai plugin note, and backfilled the missing Subagent-plugins section in thejalocale for parity with the other locales.reference/configuration.md(all 4 locales): the built-ins list omittedxai/grokand theauthenum omittedxai_oauth— a real accuracy gap now corrected.site/astro.config.mjsright after Codex, with ko/ja/zh-CN labels.Milestone / spec
Documentation for the xAI-family providers shipped in #58 (
feat(xai): add grok subscription-OAuth provider via the Grok CLI proxy). Nodocs/spec changes required — this is site-only user-facing documentation.Checklist
cargo buildpasses — N/A, no Rust source changed (docs-only)cargo testpasses — N/A, no Rust source changed (docs-only)cargo clippy --all-targets -- -D warningsclean — N/A, no Rust source changed (docs-only)cargo fmt --all --checkclean — N/A, no Rust source changed (docs-only)docs/updated if this change deviates from it — N/A, no spec deviationsite/)Notes for reviewers
astro build(65 pages, no errors) before pushing.reference/configuration.mdfixes (missingxai/grokbuiltins, missingxai_oauthauth enum) are pre-existing accuracy gaps from feat(xai): add grok subscription-OAuth provider via the Grok CLI proxy #58 landing without a docs update — bundled here since they're directly related to the new guide's accuracy.ja/guides/providers.mdpicked up a Subagent-plugins section that the other locales already had; this is a parity backfill, not new content.Summary by cubic
Adds a dedicated xAI / Grok provider guide across en/ko/ja/zh‑CN and wires it into the sidebar. Covers both
grok(subscription OAuth viashunt login xai→cli-chat-proxy.grok.com) andxai(API key toapi.x.ai) with routing, model setup, and troubleshooting.New Features
guides/xai.mdin four locales with setup forgrokandxai, routing, model slugs, opt‑in reasoning effort, context window, off‑origin token guard, web‑search caveat, example, and troubleshooting.xai/grokand added a Grok section linking the guide; added subagent‑plugin notes in ko/ja/zh‑CN listingshunt-xaiagents forgrok-4.5/grok-4.3/grok-build-0.1.Bug Fixes
xai/grokand theauthenumxai_oauth.$SHUNT_XAI_AUTH_FILE; clarified0600is the auth‑file permission; replaced the context‑window placeholder withCLAUDE_CODE_MAX_CONTEXT_TOKENS=256000; localized ja/ko code‑block comments and ja link texts.Written for commit bd1ff28. Summary will update on new commits.