Grok Code Companion

Chat with the official xAI Grok CLI without leaving VS Code —
streaming answers, agent tool activity, plans, and usage tracking in your sidebar.

This is an independent community project. It is not affiliated with, endorsed by, or sponsored by xAI. Grok and xAI are trademarks of their respective owners. Authentication, sessions, and credentials stay entirely under the official Grok CLI's control.

Features

Sidebar chat — a Grok panel in the Activity Bar with streaming Markdown answers and one-click copy for code blocks
Full agent visibility — live reasoning, plans, and collapsible tool-call cards with status indicators
Model & reasoning controls — switch between Grok 4.5 and Composer 2.5 Fast, and pick Light / Balanced / Pro reasoning right above the composer
Access modes — choose whether Grok asks for approval, auto-approves, or runs with full access per your trust level
Context tracking — a usage meter shows how much of the context window is consumed, plus session cost when the CLI reports it
Safe by design — the extension never sees your xAI password, cookies, API keys, or authentication tokens; sign-in stays under the official Grok CLI's control

Requirements

VS Code 1.96 or newer
The official xAI Grok CLI on your PATH (or set its location in settings)

Quick start

1. Install the Grok CLI

curl -fsSL https://x.ai/cli/install.sh | bash

Reopen your terminal and confirm it works:

grok --version

If grok is not found, the installer usually places it in ~/.grok/bin — add that to your PATH, or point the grok.cliPath setting at the full executable path. You can also run Grok: Install CLI from the Command Palette later.

grok login --device-auth

Or run Grok: Sign In from the Command Palette and follow the device-code instructions. This flow does not depend on a localhost browser callback. If you prefer OAuth, use Grok: Sign In with Browser Callback.

3. Chat

Open a project folder.
Click the Grok spark icon in the Activity Bar.
Ask something — try one of the starter prompts, or your own.
Enter sends, Shift+Enter adds a line, Stop cancels, + starts a new chat.

The first workspace folder becomes the agent's working directory; additional folders are shared with the session too.

Settings

Setting	What it does	Default
`grok.cliPath`	Path to the Grok CLI executable	`grok`
`grok.model`	Model for new sessions (Grok 4.5 / Composer 2.5 Fast)	`grok-4.5`
`grok.reasoningEffort`	Light / Balanced / Pro reasoning	`high`
`grok.accessMode`	Ask for approval / Approve for me / Full access	`default`
`grok.alwaysApprove`	Auto-approve every tool call (use with care)	`false`

Model, reasoning, and access are also switchable from the chat panel itself — changing one starts a fresh session so the CLI can apply it safely.

Security note: Full access and Always approve let the agent act without confirmation, with the permissions of your OS user. Only enable them in workspaces you trust.

Troubleshooting

VS Code cannot start the Grok CLI — Confirm ~/.grok/bin/grok --version works in a terminal, then set grok.cliPath to that full path in Settings.

Sign-in is required repeatedly — Run grok login --device-auth in a terminal and complete the device-code flow. The extension also restarts its CLI agent when you choose Grok: Sign In, so the next message reads the newly saved credentials.

The Grok icon does not appear — Run Grok: Open Chat from the Command Palette, or reload with Developer: Reload Window and check the extension is enabled.

Development

npm install
npm run compile   # typecheck + bundle to dist/extension.js
npm run watch     # rebuild on change

Press F5 in VS Code to launch an Extension Development Host.

Build an installable VSIX:

npm run package

Install it via Extensions → ⋯ → Install from VSIX… or:

code --install-extension grok-code-companion-0.3.0.vsix

Publish to the Marketplace

Create a publisher at marketplace.visualstudio.com/manage and make the publisher field in package.json match its ID.
Create an Azure DevOps Personal Access Token with the Marketplace → Manage scope.
Then:

npx vsce login <your-publisher-id>
npx vsce publish

Architecture & security

The extension launches grok login --device-auth in a VS Code terminal and talks to grok agent … stdio over the Agent Client Protocol. Browser-callback OAuth remains available as a separate command. The extension does not request or store account passwords, browser cookies, API keys, or authentication tokens. Tool operations require confirmation unless you opt out via settings.

License

MIT

Grok Code Companion