# Grok Build — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "Grok Build KB — Master Index" type: index updated: 2026-06-24 grok_build_model: "grok-build-0.1" --- # Grok Build KB — Master Index **Domain:** Grok Build — xAI's Grok coding agent and CLI (model `grok-build-0.1`): install and sessions, the interactive TUI, headless/scripting mode and the Agent Client Protocol (ACP), modes & commands (Plan mode), settings, custom models, skills/plugins/marketplaces, enterprise, and the Grok model + tool surface it builds on. **Corpus:** 20 provenance-stamped sources in `raw/` — the `docs.x.ai/build/*` agent docs plus the model catalog and tool/MCP developer pages (gathered as per-page Markdown; the CLI itself is closed-source). **Pages:** 13 (9 concepts · 1 entity · 1 summary · 2 syntheses). ## Concepts (core ideas + operational how-tos) - [[concepts/what-is-grok-build]] — the coding agent/CLI, the `grok-build-0.1` model, beta/early-access status, the install one-liner - [[concepts/installation-and-sessions]] — `curl -fsSL https://x.ai/cli/install.sh | bash`, starting an interactive TUI session, auth - [[concepts/modes-and-commands]] — interactive vs Plan mode (`Shift+Tab` / `/plan`), Always-approve, slash commands - [[concepts/headless-and-acp]] — headless mode for scripts/bots and the Agent Client Protocol (ACP) for embedding in other apps - [[concepts/skills-plugins-and-marketplaces]] — extending the agent: skills, plugins, and marketplaces - [[concepts/settings-and-configuration]] — the config file and its `[ui]`/`[session]`/`[toolset]` blocks - [[concepts/custom-models]] — configuring custom/alternative models (`[model.]`, `[models] default`) - [[concepts/tools-and-mcp]] — the tool surface: function calling, code execution, remote MCP, web search, docs MCP - [[concepts/enterprise]] — enterprise hosts, config layers, auth methods, sandbox profiles, permission modes ## Entities - [[entities/grok-models]] — the Grok model family the agent runs on: `grok-build-0.1` (256k, $1/$2), reasoning effort, multi-agent, pricing ## Summaries - [[summaries/xai-platform-catalog]] — map of the broader xAI platform Grok Build sits on (model catalog, API surfaces, Console) — mapped, not paged ## Syntheses (decisions & workflows) - [[syntheses/surfaces-compared]] — interactive TUI vs headless/scripting vs ACP: when to use which - [[syntheses/agentic-workflows]] — driving larger work: Plan mode (plan→execute→verify), tool/MCP use, multi-agent ## Statistics - **Total pages**: 13 - **Concepts**: 9 · **Entities**: 1 · **Summaries**: 1 · **Syntheses**: 2 - **Sources ingested**: 20 (raw/, immutable) - **High confidence**: 11 · **Medium confidence**: 2 · **Low confidence**: 0 ## Coverage notes Strong: the Grok Build agent (install, sessions, modes/commands, headless+ACP, skills/plugins, settings, custom models, enterprise) and the model/tool surface it uses. `grok-build-0.1` is in early access and the agent in beta (per release notes); freshness = source fetch date 2026-06-24. Mapped, not paged (see [[summaries/xai-platform-catalog]]): the full xAI API reference (Responses/REST/gRPC, advanced API usage), non-text model capabilities (image/video/audio/voice/Imagine generation), and the Console (billing/usage). For those and post-date changes, use docs.x.ai. Note: docs describe **Plan mode** as the autonomy surface; a separate `/goal` mode reported in press coverage was **not** present in the gathered docs — left out pending a source. --- title: "Custom Models" type: concept tags: [custom-models, config-toml, model-selection, grok-build-0.1] updated: 2026-06-24 confidence: high sources: [raw/web_community-overview-md-2.md, raw/web_community-models-md.md] --- # Custom Models Grok Build supports any custom model. Add it to your user-level config file, `~/.grok/config.toml` (on Windows, `%USERPROFILE%\.grok\config.toml`): ```text [model.my-model] model = "model-id" base_url = "https://api.example.com/v1" name = "Display Name" env_key = "API_KEY" [models] default = "my-model" ``` ## Selecting a model After updating `~/.grok/config.toml`, run `grok inspect` to confirm what Grok discovered, then pick the model in headless mode or in the TUI: ```bash grok inspect grok -p "Hello" -m my-model ``` You can also switch inside the TUI with `/model `. ## Use Grok Build 0.1 on the API The same model that powers Grok Build, `grok-build-0.1`, is also available directly on the xAI API in early access. Drop it into your own agent loop, IDE integration, or coding tool: ```bash curl https://api.x.ai/v1/responses \ -H "Authorization: Bearer $XAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-build-0.1", "input": "Refactor this function to handle null inputs." }' ``` `grok-build-0.1` has a 256k context window and is priced at $1.00 / 1M input tokens and $2.00 / 1M output tokens. See [[entities/grok-models]] for the full Grok family. ## Model aliases xAI models use aliases so you can pin or auto-migrate: `` is aliased to the latest stable version, `-latest` to the latest version, and `-` to a specific, frozen release. For most users the aliased `` or `-latest` are recommended. See also [[concepts/settings-and-configuration]], [[concepts/headless-and-acp]]. --- title: "Enterprise Deployments" type: concept tags: [enterprise, security, authentication, sandbox, permissions] updated: 2026-06-24 confidence: high sources: [raw/web_community-enterprise-md.md] --- # Enterprise Deployments Covers network requirements, configuration layering, authentication, security controls, and the data lifecycle for deploying Grok Build at scale. ## Network requirements All connections use HTTPS (port 443), TLS 1.2 or 1.3 enforced by `rustls` (no OpenSSL); there is no option to disable TLS. Required hosts: | Host | Purpose | | ---- | ------- | | `cli-chat-proxy.grok.com` | Inference proxy, settings | | `auth.x.ai` | OAuth2/OIDC authentication | Additional hosts (`api.x.ai`, `code.grok.com`, `assets.grok.com`, `x.ai`, `storage.googleapis.com`) support extra features and can be blocked without affecting core auth/inference. Installing via `npm install -g @xai-official/grok` avoids needing `x.ai`/`storage.googleapis.com`. The CLI honors `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`; set proxy idle timeouts to at least 10 minutes to avoid disconnects during long responses. ## Configuration layers Five layers, lowest to highest priority: | Priority | Source | | -------- | ------ | | 1 (lowest) | `/etc/grok/managed_config.toml` | | 2 | `~/.grok/managed_config.toml` | | 3 | `~/.grok/config.toml` | | 4 | `~/.grok/requirements.toml` | | 5 (highest) | `/etc/grok/requirements.toml` | `requirements.toml` settings are fail-closed "pins" that cannot be overridden by user config, env vars, remote settings, or lower layers. `/etc/grok/requirements.toml` is the authoritative source for compliance policy — recommended for MDM, golden images, and fleet deployments. Orgs already running Claude Code can keep their `managed-settings.json`; Grok reads a subset (permission rules, MCP allowlists, some telemetry flags, marketplace restrictions), but Grok's own `requirements.toml` always takes precedence. ## Authentication Four session auth methods: | Method | Trigger | Best for | | ------ | ------- | -------- | | Browser OIDC | `grok login` (default) | Interactive terminals with a browser | | Device code | `grok login --device-auth` | SSH, containers, headless hosts | | External auth provider | `auth_provider_command` in config | Corporate IdPs, token brokers | | API key | `XAI_API_KEY` env var or `model.api_key` | Scripts, CI/CD, headless automation | Enterprise OIDC is configured under `[auth.oidc]` (`issuer`, `client_id`) or via `GROK_OIDC_ISSUER` / `GROK_OIDC_CLIENT_ID`; the flow uses PKCE with refresh tokens. To force SSO, set `disable_api_key_auth = true`; pin logins to a team with `force_login_team_uuid` (both under `[grok_com_config]` in `requirements.toml`). ## Security controls ### Sandbox Applied once at startup, irreversible — Landlock on Linux (kernel 5.13+), Seatbelt on macOS. Profiles: `off` (default), `workspace`, `devbox`, `read-only`, `strict`. Set with `--sandbox ` or pin under `[sandbox] profile`. Directories like `~/.ssh`, `~/.gnupg`, `~/.grok/auth`, `~/.aws` are always write-protected. ### Permissions Beyond the `ask` / `always-approve` modes (see [[concepts/modes-and-commands]]), enterprise/CI modes include `dontAsk` (silently deny anything without an explicit allow rule) and `acceptEdits`. Set via `--permission-mode` (accepts `default`, `dontAsk`, `acceptEdits`, `bypassPermissions`, `plan`). Fine-grained allow/deny glob rules target tool filters `Bash`, `Edit`, `Read`, `Grep`, `MCPTool`, `WebFetch`; deny always beats allow: ```bash grok -p "Review the API changes" \ --permission-mode dontAsk \ --allow 'Bash(git *)' \ --deny 'Bash(rm -rf *)' ``` Lock always-approve off deployment-wide with `disable_bypass_permissions_mode = true` under `[ui]` — honored only from root-owned sources. ## Privacy and data lifecycle A session moves through six phases: user input, TLS transport, inference, local sandboxed tool execution, response, and session end. Zero Data Retention (ZDR) is enforced at team level; for ZDR orgs, no prompts, code, or responses are persisted at the inference layer. Local session history is stored in `~/.grok/`. Related: [[concepts/settings-and-configuration]], [[concepts/headless-and-acp]], [[concepts/tools-and-mcp]]. --- title: "Headless Mode and ACP" type: concept tags: [headless, scripting, acp, json-rpc, automation] updated: 2026-06-24 confidence: high sources: [raw/web_community-headless-scripting-md.md] --- # Headless Mode and ACP ## Headless mode Use headless mode for scripts, bots, or other machine-friendly tasks: ```bash grok -p "Your prompt here" ``` Common flags: | Flag | What it does | | ---- | ------------ | | `-p, --single ` | Send one prompt | | `-m, --model ` | Choose a model | | `-s, --session-id ` | Create or resume a named headless session | | `-r, --resume ` | Resume an existing session | | `-c, --continue` | Continue the most recent session in the current directory | | `--cwd ` | Set the working directory | | `--output-format ` | Choose `plain`, `json`, or `streaming-json` | | `--always-approve` | Auto-approve tool executions | | `--no-alt-screen` | Run inline (no fullscreen TUI takeover) | Headless sessions (`--session-id`, `--resume`, `--continue`) are stored in `~/.grok/sessions`. **Suppressing updates:** In headless (`-p`) or ACP (`grok agent stdio`) usage inside scripts/CI, pass `--no-auto-update` to skip background update checks, e.g. `grok --no-auto-update -p "..."`. To disable persistently, set `auto_update = false` under `[cli]` in `~/.grok/config.toml`. ## Output formats - `plain` — human-readable text. - `json` — one JSON object at the end. - `streaming-json` — newline-delimited JSON events emitted incrementally as they arrive. ```bash grok -p "List TODO comments" --output-format json grok -p "Explain the architecture" --output-format streaming-json ``` ## Agent Client Protocol (ACP) Use ACP when you want IDE or tool integration rather than a terminal session: ```bash grok agent stdio ``` This runs Grok as an ACP agent over **JSON-RPC on stdin/stdout**. It assumes `grok` is already authenticated locally, or `XAI_API_KEY` is set. The protocol flow (JSON-RPC methods): 1. `initialize` — exchange `protocolVersion` and client capabilities; the response lists `authMethods` (e.g. `xai.api_key`, `cached_token`). 2. `authenticate` — pass the chosen `methodId`. 3. `session/new` — open a session with a `cwd` and `mcpServers`; returns a `sessionId`. 4. `session/prompt` — send prompt content; returns completion metadata including `stopReason`. The assistant text itself arrives separately as `session/update` notifications, where `update.sessionUpdate === "agent_message_chunk"` carries `content.text` chunks. So `session/prompt` returns metadata, while streamed assistant text is delivered as `session/update` chunks. Related: [[concepts/installation-and-sessions]], [[concepts/modes-and-commands]], [[syntheses/agentic-workflows]], [[concepts/tools-and-mcp]]. --- title: "Installation and Sessions" type: concept tags: [install, tui, sessions, authentication] updated: 2026-06-24 confidence: high sources: [raw/web_community-overview-md-2.md] --- # Installation and Sessions ## Install macOS / Linux: ```bash curl -fsSL https://x.ai/cli/install.sh | bash ``` Windows (PowerShell): ```powershell irm https://x.ai/cli/install.ps1 | iex ``` ## Start an interactive session Change into your project, then launch the TUI: ```bash cd your-project grok ``` The TUI is a rich, mouse-interactive, fullscreen experience for coding with agents. Useful first prompts: ```text Explain this repo. @src/main.rs Walk me through this file. ``` The `@path` syntax pulls a specific file into context. ## Authentication On first launch, Grok opens a browser for authentication. In non-browser environments, authenticate with an API key instead: ```bash export XAI_API_KEY="xai-..." grok ``` For enterprise auth methods (browser OIDC, device code, external auth providers), see [[concepts/enterprise]]. ## Inspecting the environment `grok inspect` reports what Grok discovered in the current directory — config sources, instructions, skills, plugins, hooks, and MCP servers: ```bash grok inspect ``` ## Selecting a model Pick a model in headless mode with `-m`, or switch inside the TUI with `/model `: ```bash grok -p "Hello" -m my-model ``` Custom models are added in `~/.grok/config.toml` (on Windows, `%USERPROFILE%\.grok\config.toml`) — see [[concepts/custom-models]] and [[concepts/settings-and-configuration]]. Next: [[concepts/modes-and-commands]] for in-session controls, [[concepts/headless-and-acp]] for scripting. --- title: "Modes and Commands" type: concept tags: [tui, slash-commands, modes, plan-mode, permissions] updated: 2026-06-24 confidence: high sources: [raw/web_community-modes-and-commands-md.md] --- # Modes and Commands The TUI has pager-local slash commands plus a smaller set provided by `xai-grok-shell`. User-invocable skills also appear as slash commands. In the TUI, **`Shift+Tab` cycles session modes**. ## Modes ### Plan Plan mode is for planning first. When active, write tools are blocked except for the session plan file. Use it when you want Grok to sketch the approach before making changes; it can also stop to ask a clarifying question before edits. View the current plan with `/plan`. ### Always-approve Always-approve skips permission prompts for tool calls. Start in this mode, or toggle it from the TUI: ```bash grok --always-approve ``` Toggle in-session with `/always-approve`. ### Permission mode in config.toml Set the default permission behavior in `~/.grok/config.toml` (user-level, not project-scoped): ```text [ui] permission_mode = "always-approve" ``` `permission_mode = "ask"` prompts on each tool call; `"always-approve"` skips them. Default is `ask`. Legacy keys `approval_mode` and `yolo = true` are still accepted, but `permission_mode` takes precedence. ## Core TUI commands | Command | What it does | | ------- | ------------ | | `/quit` (alias `/exit`) | Quit the application | | `/new` | Start a new session | | `/resume` | Resume a previous session | | `/sessions` | Browse and pick from past sessions | | `/fork` | Fork the current session into a new one | | `/rename ` | Rename the current session | | `/share` | Share the current session via URL | | `/context` | View context usage | | `/model <name>` | Switch the active model | | `/compact [context]` | Compact conversation history | | `/plan` | View the current session plan | | `/btw <question>` | Ask a side question without interrupting | | `/rewind` | Rewind to an earlier point in the conversation | | `/usage` | Show token and credit usage | | `/logout` | Sign out of the current account | | `/hooks`, `/plugins`, `/skills`, `/mcps` | Open the unified extensions modal at that tab | (Other commands include `/home`, `/session-info`, `/multiline`, `/compact-mode`, `/theme`, `/feedback`.) ## Shell-provided commands | Command | What it does | | ------- | ------------ | | `/flush` | Flush conversation memory to disk now | | `/memory` | Search and edit persistent memory entries | | `/dream` | Trigger an offline memory-consolidation pass | | `/imagine <prompt>` | Generate an image from text | | `/imagine-video <prompt>` | Generate a video from text | ## Skills as commands Any user-invocable skill can appear as a slash command, e.g. `/<skill-name>`. If names collide, use the qualified form such as `/local:commit`. See [[concepts/skills-plugins-and-marketplaces]]. Related: [[concepts/installation-and-sessions]], [[concepts/tools-and-mcp]], [[concepts/enterprise]] (enterprise permission modes). <!-- ===== grok-build/wiki/concepts/settings-and-configuration.md ===== --> --- title: "Settings and Configuration" type: concept tags: [configuration, config-toml, toolset, settings] updated: 2026-06-24 confidence: high sources: [raw/web_community-settings-md.md, raw/web_community-overview-md-2.md] --- # Settings and Configuration Grok Build is configured through `~/.grok/config.toml` (on Windows, `%USERPROFILE%\.grok\config.toml`). Specify only the values you want to override; everything else falls back to built-in defaults. Settings can also be changed from the TUI Settings modal. Run `grok inspect` to see what Grok discovered in the current directory, including config sources, instructions, skills, plugins, hooks, and MCP servers. ## Common options ```text [ui] scroll_speed = 50 # mouse-wheel / trackpad scroll speed, 1-100 (higher = faster) vim_mode = false # vim-style scrollback navigation keys [session] auto_compact_threshold_percent = 85 # auto-compact at this % of context window ``` ## File toolset (hashline edits) By default Grok edits files with the standard toolset (`read_file`, `search_replace`, `grep`). You can switch to the anchor-based hashline toolset (`hashline_read`, `hashline_edit`, `hashline_grep`), which reads and edits files using stable line anchors instead of exact string matches: ```text [toolset] file_toolset = "hashline" # "standard" (default) or "hashline" [toolset.hashline] scheme = "chunk" # "chunk" (default) or "content_only" hash_len = 3 # anchor hash length, 1-4 (default 3) chunk_size = 8 # chunk size for the chunk scheme (default 8) ``` The two toolsets are mutually exclusive. The `[toolset.hashline]` parameters only apply when `file_toolset = "hashline"`. ## Other config sections The same `config.toml` also hosts extensibility paths and model definitions documented elsewhere: `[skills] paths`, `[plugins] paths`, and `[[marketplace.sources]]` (see [[concepts/skills-plugins-and-marketplaces]]), plus `[model.<name>]` blocks and `[models] default` (see [[concepts/custom-models]]). See also [[concepts/installation-and-sessions]], [[concepts/modes-and-commands]]. <!-- ===== grok-build/wiki/concepts/skills-plugins-and-marketplaces.md ===== --> --- title: "Skills, Plugins & Marketplaces" type: concept tags: [skills, plugins, marketplaces, extensibility] updated: 2026-06-24 confidence: high sources: [raw/web_community-skills-plugins-marketplaces-md.md] --- # Skills, Plugins & Marketplaces Grok Build is extended through skills, plugins, hooks, subagents, and marketplaces. Manage them all from a single extensions modal in the TUI, opened with any of `/plugins`, `/hooks`, `/skills`, or `/mcps`. ## Skills Skills are reusable folders containing markdown instructions, script files, and resources for agents. User-invocable skills also appear as slash commands, for example `/<skill-name>`. Grok discovers skills from: * `./.grok/skills/` (walked up to the repo root) * `~/.grok/skills/` * Any enabled plugin's `skills/` directory * Extra paths under `[skills] paths` in `~/.grok/config.toml` ## Plugins Plugins extend Grok with additional skills, agents, hooks, MCP servers, and LSP servers. Grok loads plugins from: * `./.grok/plugins/` * `~/.grok/plugins/` * Marketplace installs under `~/.grok/plugins/marketplaces/` * Extra paths under `[plugins] paths` in `~/.grok/config.toml` * `--plugin-dir <PATH>` on the CLI ## Hooks Hooks run scripts on tool and session lifecycle events (e.g. before or after tool calls). They are discovered from `~/.grok/hooks/` (extra roots via `~/.grok/hooks-paths`), project `.grok/hooks/` (requires `/hooks-trust`), and enabled plugins. All hooks receive `GROK_HOOK_EVENT`, `GROK_HOOK_NAME`, `GROK_SESSION_ID`, and `GROK_WORKSPACE_ROOT`; plugin hooks also receive `GROK_PLUGIN_ROOT` and `GROK_PLUGIN_DATA`. ## Marketplaces & Subagents The TUI includes a Marketplace tab for browsing and installing plugins. Sources come from `[[marketplace.sources]]` in `~/.grok/config.toml` and `~/.grok/plugins/known_marketplaces.json`. Subagents spawn independent child sessions that handle tasks in parallel. ## Compatibility Grok is fully compatible with Claude Code with zero configuration — it automatically reads Claude Code marketplaces, plugins, skills, MCPs, agents, hooks, and instruction files (`CLAUDE.md`, `Claude.md`, `CLAUDE.local.md`, `.claude/rules/`) alongside `.grok/`. Grok also reads the `AGENTS.md` family (`AGENTS.md`, `Agents.md`, `AGENT.md`) walked from cwd to repo root, plus user-level skills/commands from `~/.agents/skills/` and `~/.agents/commands/`. See also [[concepts/settings-and-configuration]], [[concepts/tools-and-mcp]], [[concepts/modes-and-commands]]. <!-- ===== grok-build/wiki/concepts/tools-and-mcp.md ===== --> --- title: "Tools and MCP" type: concept tags: [tools, function-calling, mcp, web-search, code-execution] updated: 2026-06-24 confidence: high sources: [raw/web_community-overview-md-3.md, raw/web_community-function-calling-md.md, raw/web_community-code-execution-md.md, raw/web_community-remote-mcp-md.md, raw/web_community-web-search-md.md, raw/web_community-docs-mcp-md.md] --- # Tools and MCP The xAI API supports **tool calling**, letting Grok search the web, execute code, query data, or call your own functions. There are two categories: **built-in tools** (server-side, run on xAI's servers and execute automatically) and **function calling** (custom functions you define and execute yourself). Built-in tools execute automatically; custom tools pause execution and return to you for handling. ```bash curl https://api.x.ai/v1/responses \ -H "Authorization: Bearer $XAI_API_KEY" \ -d '{ "model": "grok-4.3", "input": [{"role":"user","content":"What are the latest updates from xAI?"}], "tools": [ { "type": "web_search" }, { "type": "x_search" }, { "type": "code_interpreter" } ] }' ``` ## Function calling Define custom tools with a `name`, `description`, and a JSON Schema `parameters` object. The model returns a `tool_call`; you execute it locally and return the result. ```json { "type": "function", "name": "get_temperature", "description": "Get current temperature for a location", "parameters": { "type": "object", "properties": { "location": {"type": "string", "description": "City name"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "fahrenheit"} }, "required": ["location"] } } ``` The `parameters` root must be an object (or a `oneOf`/`anyOf` of objects). Control invocation with `tool_choice` (`"auto"`, `"required"`, `"none"`, or `{"type":"function","function":{"name":"..."}}`). Parallel calls are on by default; disable with `parallel_tool_calls: false`. Max 200 tools per request. ## Code execution & web search Code execution runs Python in a sandboxed, stateless environment (NumPy, Pandas, Matplotlib, SciPy available; no network/file-system access). Tool name is `code_execution` in the xAI SDK and `code_interpreter` in the OpenAI Responses API. Web search (`web_search`) browses the live web; parameters include `allowed_domains` / `excluded_domains` (max 5 each, mutually exclusive), `enable_image_understanding`, and `enable_image_search`. ## Remote MCP servers Remote MCP tools let Grok connect to external Model Context Protocol servers — you specify a server URL and xAI manages the connection. Only Streaming HTTP and SSE transports are supported. ```json { "type": "mcp", "server_url": "https://mcp.deepwiki.com/mcp", "server_label": "deepwiki" } ``` Required: `server_url`, `server_label`. Optional: `server_description`, `allowed_tools` (SDK name `allowed_tool_names`), `authorization`, `headers` (SDK name `extra_headers`). Without `allowed_tools`, all of a server's tools are injected into context. Multiple servers can be enabled simultaneously. ## Docs MCP server xAI hosts a docs MCP server at `https://docs.x.ai/api/mcp` (Streamable HTTP, stateless) that gives any MCP-compatible client direct access to xAI documentation. Tools include `list_doc_pages`, `get_doc_page`, and `search_docs`. See also [[concepts/skills-plugins-and-marketplaces]], [[entities/grok-models]], [[concepts/settings-and-configuration]]. <!-- ===== grok-build/wiki/concepts/what-is-grok-build.md ===== --> --- title: "What Is Grok Build" type: concept tags: [grok-build, coding-agent, cli, grok-build-0.1] updated: 2026-06-24 confidence: high sources: [raw/web_community-overview-md-2.md, raw/web_community-models-md.md, raw/web_community-release-notes-md.md] --- # What Is Grok Build Grok Build is xAI's coding agent and CLI — "a powerful and extensible coding agent." You use it via an interactive TUI, headlessly in scripts or bots, or through the Agent Client Protocol (ACP) embedded in other apps. The TUI is "a rich, mouse-interactive, fullscreen experience for coding with agents." It is a peer to other coding agents in the xAI ecosystem. Per the release notes, Grok Build "is now available in beta." ## The model: grok-build-0.1 Grok Build is powered by `grok-build-0.1`, "xAI's fast coding model trained specifically for agentic coding, currently in early access." The same model is also available directly on the xAI API so you can "drop it into your own agent loop, IDE integration, or coding tool": ```bash curl https://api.x.ai/v1/responses \ -H "Authorization: Bearer $XAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "grok-build-0.1", "input": "Refactor this function to handle null inputs." }' ``` From the model pricing table, `grok-build-0.1` has a **256k context**, priced at **$1.00 / 1M input tokens** and **$2.00 / 1M output tokens** — distinct from the general `grok-4.3` chat/coding model (1M context, $1.25 / $2.50). ## Install ```bash curl -fsSL https://x.ai/cli/install.sh | bash ``` ## Three surfaces - **Interactive TUI** — `grok` in a project directory. See [[concepts/installation-and-sessions]] and [[concepts/modes-and-commands]]. - **Headless** — `grok -p "..."` for scripts and automations. - **ACP** — `grok agent stdio` for IDE/tool embedding. Both covered in [[concepts/headless-and-acp]]. See also [[entities/grok-models]] and [[summaries/xai-platform-catalog]]. <!-- ===== grok-build/wiki/entities/grok-models.md ===== --> --- title: "Grok Models" type: entity tags: [models, pricing, reasoning, grok-build-0.1, grok-4.3] updated: 2026-06-24 confidence: high sources: [raw/web_community-models-md.md, raw/web_community-reasoning-md.md, raw/web_community-generate-text-md.md, raw/web_community-pricing-md.md] --- # Grok Models The Grok model family powers Grok Build and the xAI Responses API. `grok-build-0.1` is the coding model behind the Grok Build agent; `grok-4.3` is the general-purpose flagship ("the most intelligent and fastest model we've built"), recommended for both chat and coding. ## Model pricing & context | Model | Context | Input / 1M tokens | Output / 1M tokens | | --- | --- | --- | --- | | grok-4.3 | 1M | $1.25 | $2.50 | | grok-4.20-0309-reasoning | 1M | $1.25 | $2.50 | | grok-4.20-0309-non-reasoning | 1M | $1.25 | $2.50 | | grok-build-0.1 | 256k | $1.00 | $2.00 | | grok-4.20-multi-agent-0309 | 1M | $1.25 | $2.50 | `grok-build-0.1` is available on the xAI API in early access (see [[concepts/custom-models]]). ## Reasoning Reasoning models think step-by-step before answering and expose `reasoning_tokens` in usage. `grok-4.3` supports the `reasoning_effort` parameter, defaulting to `"low"`: | Setting | Behavior | |---|---| | `"none"` | Disables reasoning entirely | | `"low"` (default) | Some reasoning, still fast — general agentic use and tool calling | | `"medium"` | More thinking for complex analysis and long-context reasoning | | `"high"` | Deeper thinking for very challenging problems, complex math, multi-step logic | For `grok-4.20-multi-agent`, `reasoning.effort` (`"low"`/`"medium"`/`"high"`/`"xhigh"`) controls **how many agents** collaborate (4 or 16), not reasoning depth. `presencePenalty`, `frequencyPenalty`, and `stop` cannot be used with reasoning models. Encrypted reasoning can be returned via `include: ["reasoning.encrypted_content"]`. ## API behavior Models are accessed through the Responses API (`https://api.x.ai/v1/responses`). It supports **stateful** interactions: previous prompts, reasoning, and responses are stored on xAI servers for **30 days** by default; continue a conversation by passing `previous_response_id`. Set `store: false` to opt out. `logprobs` and `top_logprobs` are not supported by `grok-4.20` and newer (silently ignored). The Grok 3 and Grok 4 knowledge cut-off is November 2024; realtime data requires server-side search tools. ## Model aliases `<modelname>` → latest stable; `<modelname>-latest` → latest version; `<modelname>-<date>` → a specific frozen release. See also [[concepts/custom-models]], [[concepts/tools-and-mcp]], [[summaries/xai-platform-catalog]]. <!-- ===== grok-build/wiki/log.md ===== --> --- title: "Activity Log" type: log --- # Activity Log Append-only record of all wiki changes. ## Format Each entry follows this format: ``` ### YYYY-MM-DD HH:MM — [Action Type] - **Source/Trigger**: what initiated the action - **Pages created**: list of new pages - **Pages updated**: list of updated pages - **Notes**: any contradictions flagged, decisions made ``` --- ### 2026-04-08 00:00 — Setup - **Source/Trigger**: Repository initialized - **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md - **Pages updated**: none - **Notes**: Empty knowledge base ready for first source ingestion --- ### 2026-06-24 — Initial curation (factory build) - **Source/Trigger**: `new_wiki.py init grok-build` — 20 sources gathered from docs.x.ai (per-page Markdown via web_urls: the 6 `/build/*` agent pages + model/tools developer pages). The CLI is closed-source (curl installer); the x.ai/news announcement is bot-walled (403). - **Pages created**: 13 — 9 concepts (what-is-grok-build, installation-and-sessions, modes-and-commands, headless-and-acp, skills-plugins-and-marketplaces, settings-and-configuration, custom-models, tools-and-mcp, enterprise), 1 entity (grok-models), 1 summary (xai-platform-catalog), 2 syntheses (surfaces-compared, agentic-workflows) - **Pages updated**: index.md, log.md - **Notes**: Source-faithfulness flags during curation — (1) press coverage describes a `/goal` autonomous mode, but the gathered docs document **Plan mode** (`Shift+Tab` / `/plan`) + Always-approve instead; wrote to the docs, not the press claim. (2) "SuperGrok / X Premium+" eligibility from press was not in any gathered source; used the docs' "beta / early access" phrasing only. Both gaps noted for a future re-gather if a source page appears. <!-- ===== grok-build/wiki/summaries/xai-platform-catalog.md ===== --> --- title: "xAI Platform Catalog" type: summary tags: [xai, platform, models, api, console] updated: 2026-06-24 confidence: high sources: [raw/web_community-overview-md.md, raw/web_community-models-md.md, raw/web_community-pricing-md.md, raw/web_community-release-notes-md.md] --- # xAI Platform Catalog Grok Build (the `grok-build-0.1` coding agent and CLI — see [[concepts/what-is-grok-build]]) sits on top of the broader xAI developer platform. This page is a **map** of what that platform offers: what exists, where it lives, and which pieces this wiki does *not* document on their own pages. Source fetch date: 2026-06-24. ## Models (the catalog) Grok models span several modalities ([[entities/grok-models]]). Text/reasoning models share a 1M-token context and `$1.25 / $2.50` per-1M input/output pricing: `grok-4.3` (the recommended general/coding model), `grok-4.20-0309-reasoning`, `grok-4.20-0309-non-reasoning`, and `grok-4.20-multi-agent-0309`. The coding model `grok-build-0.1` has a 256k context at `$1.00 / $2.00`. Generation modalities are separate APIs and models: - **Imagine API (Images)** — `grok-imagine-image` ($0.02/image), `grok-imagine-image-quality` ($0.05/image). - **Imagine API (Video)** — `grok-imagine-video` ($0.050/sec), `grok-imagine-video-1.5` ($0.080/sec). - **Voice API** — Realtime ($0.05/min), Text-to-Speech ($15.00/1M chars), Speech-to-Text ($0.10/hr REST). Custom voice cloning is supported. Aliases: `<model>` / `<model>-latest` track the newest version; `<model>-<date>` pins a release. ## API surfaces - **Responses API** — the primary stateful surface for text, chat, function calling, and tool use; base URL `https://api.x.ai/v1`. OpenAI-SDK compatible. - **REST / gRPC reference** — the REST inference reference, plus the gRPC Python xAI SDK (note: `code_interpreter` and `file_search` tool names are not supported on gRPC). - **Advanced API usage** — Batch API (async, 20%–50% off, ~24h), Prompt Caching, Context Compaction, Priority Processing (`service_tier: "priority"`, 2x), and WebSocket Responses mode for tool-heavy loops. - **Tools** — server-side `web_search`, `x_search`, `code_execution`, `collections_search`, plus function calling and remote MCP. See [[concepts/tools-and-mcp]] and [[syntheses/agentic-workflows]]. ## Console & resources The xAI **Console** (`console.x.ai`) handles billing, usage, audit logs, model availability, and the tokenizer playground. **Files** ($0.025/GiB/day) and **Collections** (RAG, $0.10/GiB/day) storage are managed there or via API. Other resources: Cookbook, API reference, community integrations, and release notes. ## Freshness — latest highlights The newest release-notes entries (June): **Priority Processing** and **Public URLs for Files + Imagine ↔ Files integration**. Recent prior: **Grok Build** (beta) and **`grok-build-0.1`** (early access), Context Compaction, and WebSocket Responses mode. ## What this wiki pages separately Surfaces and workflows are covered in [[syntheses/surfaces-compared]] and [[syntheses/agentic-workflows]]; the agent itself in [[concepts/what-is-grok-build]], [[concepts/installation-and-sessions]], and [[concepts/enterprise]]. <!-- ===== grok-build/wiki/syntheses/agentic-workflows.md ===== --> --- title: "Agentic Workflows: Driving Larger Work with Grok" type: synthesis tags: [grok-build, goal, tools, mcp, multi-agent] updated: 2026-06-24 confidence: medium sources: [raw/web_community-modes-and-commands-md.md, raw/web_community-multi-agent-md.md, raw/web_community-overview-md-3.md, raw/web_community-code-execution-md.md, raw/web_community-web-search-md.md] --- # Agentic Workflows: Driving Larger Work with Grok How to push Grok beyond single edits into autonomous, multi-step work: planning modes, tools/MCP, and multi-agent research. Confidence is medium — this stitches together several docs and is interpretive. ## Plan-first and autonomous modes In the TUI, session modes (`Shift+Tab` to cycle) shape how much the agent does on its own. **Plan mode** makes Grok sketch the approach before touching code — write tools are blocked except the session plan file, and it can stop to ask a clarifying question; `/plan` shows the working plan. Pairing planning with **Always-approve** (`grok --always-approve`, `/always-approve`, or `permission_mode = "always-approve"` in `~/.grok/config.toml`) lets a vetted plan execute without per-tool prompts — effectively a plan→execute→verify loop. See [[concepts/modes-and-commands]] and [[concepts/settings-and-configuration]]. ## Tools — what extends the agent The xAI API supports **tool calling** in two categories: **built-in server-side tools** (managed and executed by xAI) and **function calling** (your own custom functions). The agent loop is autonomous: it analyzes the query, decides to call a tool or answer, executes, processes results, and repeats until done — returning citations where applicable. Built-in tools include `web_search`, `x_search`, `code_execution` (a.k.a. `code_interpreter` on the OpenAI-compatible API), and `collections_search`. See [[concepts/tools-and-mcp]]. - **Web Search** — real-time search and page browsing; scope with `allowed_domains`/`excluded_domains` (max 5 each, mutually exclusive), and enable `enable_image_understanding` or `enable_image_search`. Returns source citations. - **Code Execution** — writes and runs Python in a sandboxed, stateless environment (NumPy/Pandas/Matplotlib/SciPy available; no network or persistent filesystem) for exact calculation, data analysis, and verification. Best paired with a reasoning model like `grok-4.3`. **MCP** extends this further: remote MCP servers contribute their own tools, billed by token usage. In the TUI, manage tools and servers via the extensions modal (`/mcps`, `/skills`, `/plugins`, `/hooks`). ## Multi-agent research For deep, multi-step research, the dedicated **`grok-4.20-multi-agent`** model (beta) orchestrates a team of specialized agents in real time. They search, cross-reference, synthesize, and iterate; a **leader agent** synthesizes the final answer. Only the leader's tool calls and output are returned by default — sub-agent state is encrypted and surfaced only with `use_encrypted_content`. Depth is tunable: **4 agents** (`agent_count=4`, or `reasoning.effort` `"low"`/`"medium"`) for focused queries; **16 agents** (`agent_count=16`, or effort `"high"`/`"xhigh"`) for complex topics — at higher token cost and latency. It supports built-in and remote MCP tools but **not** client-side function calling, **not** the Chat Completions API (use the xAI SDK or Responses API), and **not** `max_tokens`. Multi-turn refinement works via `previous_response_id`. Prompt for results by setting explicit scope/dimensions, requesting structured output, and breaking deep topics into a turn-by-turn conversation. ## Putting it together Plan-first modes govern autonomy at the agent level; tools and MCP give it reach; multi-agent gives it research depth. For where these run, see [[syntheses/surfaces-compared]]; for the platform around them, [[summaries/xai-platform-catalog]] and [[concepts/skills-plugins-and-marketplaces]]. <!-- ===== grok-build/wiki/syntheses/surfaces-compared.md ===== --> --- title: "Grok Build Surfaces Compared: TUI vs Headless vs ACP" type: synthesis tags: [grok-build, tui, headless, acp] updated: 2026-06-24 confidence: medium sources: [raw/web_community-overview-md-2.md, raw/web_community-headless-scripting-md.md, raw/web_community-modes-and-commands-md.md] --- # Grok Build Surfaces Compared: TUI vs Headless vs ACP Grok Build is one coding agent exposed through three surfaces: an **interactive TUI**, **headless/scripting** mode, and the **Agent Client Protocol (ACP)** for embedding. All three share the same install (`curl -fsSL https://x.ai/cli/install.sh | bash`, or `irm https://x.ai/cli/install.ps1 | iex` on Windows) and the same `grok` binary. This is a decision guide for picking among them. Confidence is medium — interpretive synthesis of the docs below. ## Interactive TUI — for humans coding live Launch with `grok` inside a project. It is a "rich, mouse-interactive, fullscreen" experience: you converse, reference files with `@path`, and drive work through slash commands and session **modes** (`Shift+Tab` cycles modes; Plan mode blocks writes while sketching, Always-approve skips tool prompts). It carries session state — `/resume`, `/fork`, `/share`, `/compact`, `/model <name>` — plus the extensions modal (`/skills`, `/plugins`, `/mcps`, `/hooks`). See [[concepts/modes-and-commands]]. **Use it when** a person is iterating interactively and wants visible plans, approvals, and session history. This is the default surface. ## Headless / scripting — for machines Run one prompt and exit: `grok -p "Explain this codebase"`. Built for scripts, bots, CI, and automations. Key flags: `-m` (model), `-s`/`-r`/`-c` (named session create/resume/continue, stored in `~/.grok/sessions`), `--cwd`, `--always-approve` (auto-approve tools), `--no-alt-screen` (run inline), and `--output-format` = `plain` | `json` | `streaming-json`. In automated environments add `--no-auto-update` (or set `auto_update = false` under `[cli]` in config). The `json` format emits one object at the end; `streaming-json` emits newline-delimited events as they arrive. **Use it when** another program drives the agent non-interactively and you need parseable output. See [[concepts/headless-and-acp]]. ## ACP — for embedding in other apps `grok agent stdio` runs Grok as an **Agent Client Protocol** agent over JSON-RPC on stdin/stdout. The client `initialize`s (negotiating `authMethods` such as `xai.api_key` or `cached_token`), `authenticate`s, opens `session/new`, then sends `session/prompt`; the assistant text streams back as `session/update` `agent_message_chunk` events while `session/prompt` returns completion metadata. **Use it when** you are integrating Grok into an IDE or another tool — i.e. you want a long-lived embedded agent with a structured protocol rather than a terminal session or a one-shot script. As with headless, pass `--no-auto-update` in automated contexts. ## Choosing quickly | Need | Surface | |------|---------| | A person coding interactively, with plans/approvals/history | **TUI** (`grok`) | | A script/bot/CI step with parseable output | **Headless** (`grok -p`) | | Embedding the agent inside an IDE or app | **ACP** (`grok agent stdio`) | To drive larger autonomous work across any surface, see [[syntheses/agentic-workflows]]. For setup and sessions, [[concepts/installation-and-sessions]]; custom backends, [[concepts/custom-models]].