VS Code Client for Grok Build (Unofficial)

Deutsch: docs/de/README.md — full documentation in German (same content as English).

Hybrid architecture: native Visual Studio Code UX on top of the official xAI Grok Build CLI via the Agent Client Protocol (grok agent stdio).

• The extension does not reimplement the agent loop.
• Each chat session owns its own grok agent stdio process.
• VS Code supplies UI, context, multi-session, diffs, history, and editor integration.

Unofficial community project. Not affiliated with, sponsored by, or endorsed by xAI. "Grok" and "Grok Build" are trademarks of xAI and are used here only to describe compatibility with the official Grok Build CLI. Planning, tools, MCP, sub-agents, and safety stay in the official CLI.

User guide: English · Deutsch
Docs index: docs/README.md (docs/en/ + docs/de/)
UI language: English.

Features

Prerequisites

1. VS Code 1.90+ (or compatible)
2. Grok Build CLI installed and authenticated — x.ai/cli
   • grok --version — 1.0.67 or newer recommended (tested with 1.0.67 stable; older 1.0.x works with a warning banner)
3. Node.js 18+ only if you build from source

Install

Extension id: bhu.grok-build-vscode. Step-by-step guide (EN/DE): docs/en/INSTALL_VSIX.md · docs/de/INSTALL_VSIX.md

From the VS Code Marketplace (coming soon)

Not published yet. This section applies once the first store release is live.

1. Open Extensions (Ctrl+Shift+X, Mac: Cmd+Shift+X).
2. Search for Grok Build (or bhu.grok-build-vscode) and click Install.

Or from a terminal: code --install-extension bhu.grok-build-vscode

From Open VSX (coming soon)

Not published yet. For VSCodium, Cursor, Windsurf, Gitpod and other editors that use Open VSX.

Search for Grok Build in the editor's Extensions view, or open https://open-vsx.org/extension/bhu/grok-build-vscode once it is published.

Store installs are updated by the editor automatically; the built-in GitHub release check is disabled for them.

Manual VSIX install (alternative)

Use this for pre-release builds, offline machines, or until the store listings are live.

1. Releases → download grok-build-vscode-….vsix (not "Source code").
2. Press Ctrl+Shift+P (Mac: Cmd+Shift+P) → run Extensions: Install from VSIX… (German UI: Erweiterungen: Von VSIX installieren…) → pick the file → Reload if asked. Alternative: Extensions view → … menu (next to the search box) → Install from VSIX….
3. Or from a terminal:

code --install-extension path/to/grok-build-vscode-x.y.z.vsix

Manual VSIX installs check GitHub Releases for newer versions and show a hint in the chat header (turn off with grokBuild.checkExtensionUpdates).

Installed an earlier VSIX (publisher bhuertgen, versions ≤ 0.3.3)? The publisher changed to bhu, so VS Code treats the new build as a different extension. Uninstall the old Grok Build for VS Code entry first to avoid two copies.

Build locally

npm install
npm run build
npm run package
code --install-extension grok-build-vscode-x.y.z.vsix

x.y.z = the version in the .vsix file name (npm run package uses the version from package.json).

Development

npm install
npm run watch   # F5 → Extension Development Host

Quick usage

Example prompts

@README.md
Summarize installation in 3 bullets.

Create docs/notes.md with a short project intro. Stay inside this workspace.

More examples and every setting: docs/en/USER_GUIDE.md (DE).

Important settings

Trust the workspace for writes/tools. First-run recommendations: INSTALL_VSIX §7 · DE.

Complete parameter reference (CLI flags, UI permissions, context, updates):
→ docs/en/USER_GUIDE.md §6 · DE

Documentation index

Architecture (hybrid)

VS Code UI  ──►  SessionManager  ──►  AcpClient × N  ──►  grok agent stdio
 (webview)        multi-session         1 process/session     (official CLI)

Effective spawn shape:

grok [--permission-mode … --max-turns … top-level flags…] agent --no-leader -m <model> [--reasoning-effort … --always-approve --debug] stdio

Policy flags (--permission-mode, --max-turns, --no-subagents, --no-plan, --disable-web-search, --sandbox, --tools, --disallowed-tools, --rules) are top-level grok options and go before agent — grok agent rejects them (#37).

Automated checks

npm test                 # unit tests
npm run smoke            # typecheck + build + static checks + unit
npm run test:integration # real Extension Host
npm run test:all

Privacy / Data collection

• No telemetry. The extension itself sends no telemetry and collects no usage data.
• Chats, prompts and files are processed by the locally installed Grok CLI (grok agent stdio), under your own xAI / Grok account and xAI's terms. The extension only passes your prompts and the context you attach (files, selection, images) to that local process. The CLI also runs its own update check (grok update --check).
• Update check (manual VSIX installs only): the extension asks the GitHub Releases API (api.github.com) for a newer version. Store installs (VS Code Marketplace / Open VSX) skip it. Turn it off with grokBuild.checkExtensionUpdates: false.
• GitHub token: the optional grokBuild.githubToken, or an existing VS Code GitHub sign-in, is sent only to api.github.com for that check (e.g. for a private repo) and is used nowhere else.
• Local storage: chat history stays on your machine in VS Code's extension storage.
• VS Code telemetry is governed by VS Code's own settings (telemetry.telemetryLevel), not by this extension.

Details: docs/en/USER_GUIDE.md §8.1 · DE

Security

• No API keys in this repository.
• CLI auth is handled by the official grok login.
• Optional grokBuild.githubToken is local-only for private release checks.
• Chat history lives in VS Code globalState on the user machine.
• Prefer a trusted workspace for writes and tools.

Known limitations

• MCP: CLI loads its own user/global MCP config; extension passes an empty MCP list into session/new by default.
• Sub-agents: monitored via tool timeline / status strip (no per-subagent editor tabs).
• Install path: VSIX / GitHub Releases today; VS Code Marketplace and Open VSX listings are coming soon.
• Session resume needs CLI session/resume (or load); otherwise local history + new agent process.

License

MIT

Trademarks

This is an independent, unofficial community extension. It is not affiliated with, sponsored by, or endorsed by xAI. Grok is a trademark of xAI. All other trademarks belong to their respective owners.

References

• Agent Client Protocol
• Grok Build / xAI CLI
• ACP schema
• Releases