# Grok Build Documentation

> Technical documentation for the grok CLI/TUI agent: install and auth, interactive and headless runtimes, ACP integration, configuration surfaces, extension points (MCP, skills, plugins, hooks), sandbox and permissions, and reference for flags, slash commands, and key bindings.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458)
- [GitHub repository](https://github.com/xai-org/grok-build)

## Repository

- Repository: xai-org/grok-build

- Generated: 2026-07-16T02:37:47.853Z
- Updated: 2026-07-16T02:39:06.119Z
- Runtime: Grok CLI · grok-4.5
- Format: Documentation
- Pages: 25

## Pages

- [Overview](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/01-overview.md): What Grok Build exposes (interactive TUI, headless -p, ACP agent), who should use each surface, and the shortest path from install to a successful first turn.
- [Installation](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/02-installation.md): Install and update the released grok binary on macOS, Linux, and Windows; PATH layout under ~/.grok/bin; version pin flags; verify with grok --version.
- [Quickstart](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/03-quickstart.md): First interactive session: launch grok, authenticate, send a prompt, use @ file attachments, cancel turns, and confirm tool output in the TUI scrollback.
- [Authentication](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/04-authentication.md): Browser OAuth (auth.x.ai), device-code flow, XAI_API_KEY for CI, grok login/logout, credential storage in ~/.grok/auth.json, and token refresh behavior.
- [Sessions](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/05-sessions.md): Session lifecycle: create, resume, continue, fork, compact, export; persistence layout; /new /resume /compact; grok sessions subcommands and ID constraints.
- [Permissions and safety](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/06-permissions-and-safety.md): Tool authorization pipeline: PreToolUse hooks, allow/deny/ask rules, remembered grants, permission modes (including bypassPermissions/dontAsk), safe-bash defaults, and interaction with sandbox.
- [Project rules and memory](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/07-project-rules-and-memory.md): AGENTS.md discovery and precedence; cross-session memory (/flush, /dream, hybrid search); when rules inject into the system prompt versus when memory retrieval runs.
- [Configure Grok](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/08-configure-grok.md): How to set config.toml and pager.toml, precedence (CLI > env > user config > managed/requirements > defaults), feature flags, and grok inspect to dump resolved settings.
- [Custom models](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/09-custom-models.md): Select models via -m and /model; configure BYOK and OpenAI-compatible or Ollama endpoints; per-model overrides; grok models listing and provider-neutral endpoint settings.
- [MCP servers](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/10-mcp-servers.md): Register MCP servers in config.toml (stdio and HTTP), timeouts and env, enable/disable, OAuth-related MCP credentials, and grok mcp management commands.
- [Skills](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/11-skills.md): SKILL.md package layout, discovery paths (.grok, .agents, .claude, .cursor), priority and ignore rules, slash-command surface, and config toggles for vendor skill trees.
- [Plugins](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/12-plugins.md): Install and trust plugins that bundle skills, commands, agents, hooks, MCP, and LSP; marketplace sources; plugin.json conventions; GROK_PLUGIN_ROOT and GROK_PLUGIN_DATA.
- [Hooks](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/13-hooks.md): Lifecycle hooks (PreToolUse, PostToolUse, SessionStart, and peers): JSON discovery, shell vs HTTP runners, deny/allow results, environment variables, and safety patterns.
- [Headless mode](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/14-headless-mode.md): Non-interactive runs with -p/--single, --prompt-file, --prompt-json; output formats plain/json/streaming-json; tool allow/deny lists, max-turns, resume/continue, and CI patterns.
- [Agent mode (ACP)](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/15-agent-mode-acp.md): Run grok agent stdio as an Agent Client Protocol server for IDEs and custom clients; JSON-RPC session lifecycle, streaming, permissions, and options shared with agent subcommands.
- [Sandbox profiles](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/16-sandbox-profiles.md): OS-level isolation profiles (workspace, read-only, strict, devbox, off), --sandbox flag, custom deny globs, Linux vs macOS enforcement differences for child network.
- [Subagents and personas](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/17-subagents-and-personas.md): Spawn and constrain child agents: agent types, personas, capability modes, isolation/worktree behavior, and headless Agent(...) denylist entries.
- [Plan mode](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/18-plan-mode.md): Structured planning before edits: plan files, approval gates, mode entry/exit from the TUI, and how plan mode interacts with tools and permissions.
- [Theming](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/19-theming.md): TUI appearance: /theme, pager.toml theme keys, color-support detection, screen modes (fullscreen/minimal), and terminal capability constraints.
- [CLI reference](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/20-cli-reference.md): Top-level grok commands and flags: default TUI, agent, login/logout, mcp, plugin, memory, models, sessions, inspect, setup, update, wrap, export, trace; shared runtime flags.
- [Configuration reference](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/21-configuration-reference.md): Schema-oriented keys for ~/.grok/config.toml and pager.toml: [cli], [models], [ui], [features], [session], [tools], [mcp_servers], [skills], [compat], permissions, sandbox, and env var counterparts.
- [Slash commands](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/22-slash-commands.md): Interactive / commands for sessions, models, memory, hooks, plugins, themes, and more; pager vs shell builtins; skill-provided commands in the autocomplete menu.
- [Keyboard shortcuts](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/23-keyboard-shortcuts.md): TUI key bindings for prompt and scrollback focus, cancel, rewind, vim mode, mouse actions, and multi-key Escape behavior with timing constraints.
- [Troubleshooting](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/24-troubleshooting.md): Terminal support issues (tmux, SSH, truecolor, OSC 52 clipboard), color warnings, auth recovery, MCP startup failures, and diagnostics probes backed by the pager diagnostics module.
- [Build from source](https://grok-wiki.com/public/docs/xai-org-grok-build-90205de50458/pages/25-build-from-source.md): Workspace build of xai-grok-pager-bin: Rust toolchain pin, protoc/dotslash, cargo run/check/test per-crate, binary name xai-grok-pager vs shipped grok, and contribution policy constraints.

## Source Files

- `bin/protoc`
- `Cargo.toml`
- `clippy.toml`
- `CONTRIBUTING.md`
- `crates/codegen/xai-acp-lib/src/gateway.rs`
- `crates/codegen/xai-acp-lib/src/lib.rs`
- `crates/codegen/xai-agent-lifecycle/src/lib.rs`
- `crates/codegen/xai-chat-state/src/lib.rs`
- `crates/codegen/xai-grok-agent/src`
- `crates/codegen/xai-grok-auth/src/lib.rs`
- `crates/codegen/xai-grok-config-types/src/lib.rs`
- `crates/codegen/xai-grok-config-types/src/mcp.rs`
- `crates/codegen/xai-grok-config-types/src/permission.rs`
- `crates/codegen/xai-grok-config/src/loader.rs`
- `crates/codegen/xai-grok-config/src/paths.rs`
- `crates/codegen/xai-grok-config/src/validation.rs`
- `crates/codegen/xai-grok-env/src`
- `crates/codegen/xai-grok-hooks/src/discovery.rs`
- `crates/codegen/xai-grok-hooks/src/dispatcher.rs`
- `crates/codegen/xai-grok-hooks/src/event.rs`
- `crates/codegen/xai-grok-hooks/src/runner`
- `crates/codegen/xai-grok-mcp/src/lib.rs`
- `crates/codegen/xai-grok-mcp/src/servers.rs`
- `crates/codegen/xai-grok-mcp/src/wire.rs`
- `crates/codegen/xai-grok-memory/src/dream.rs`
- `crates/codegen/xai-grok-memory/src/lib.rs`
- `crates/codegen/xai-grok-memory/src/search.rs`
- `crates/codegen/xai-grok-models/src/catalog.rs`
- `crates/codegen/xai-grok-models/src/lib.rs`
- `crates/codegen/xai-grok-pager-bin/Cargo.toml`
- `crates/codegen/xai-grok-pager-bin/src/main.rs`
- `crates/codegen/xai-grok-pager-render/src`
- `crates/codegen/xai-grok-pager/docs/custom-hooks.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/01-getting-started.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/02-authentication.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/03-keyboard-shortcuts.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/04-slash-commands.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/05-configuration.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/06-theming.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/07-mcp-servers.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/08-skills.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/09-plugins.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/10-hooks.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/11-custom-models.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/12-project-rules.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/13-memory.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/14-headless-mode.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/15-agent-mode.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/16-subagents.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/17-sessions.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/18-sandbox.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/19-plan-mode.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/21-terminal-support.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/22-permissions-and-safety.md`
- `crates/codegen/xai-grok-pager/docs/user-guide/README.md`
- `crates/codegen/xai-grok-pager/scripts/install.ps1`
- `crates/codegen/xai-grok-pager/scripts/install.sh`
- `crates/codegen/xai-grok-pager/src/app/cli.rs`
- `crates/codegen/xai-grok-pager/src/app/dispatch/router.rs`
- `crates/codegen/xai-grok-pager/src/app/mod.rs`
- `crates/codegen/xai-grok-pager/src/diagnostics.rs`
- `crates/codegen/xai-grok-pager/src/headless.rs`
- `crates/codegen/xai-grok-pager/src/input`
- `crates/codegen/xai-grok-pager/src/mcp_cmd.rs`
- `crates/codegen/xai-grok-pager/src/memory_cmd.rs`
- `crates/codegen/xai-grok-pager/src/models.rs`
- `crates/codegen/xai-grok-pager/src/plugin_cmd.rs`
- `crates/codegen/xai-grok-pager/src/sessions_cmd.rs`
- `crates/codegen/xai-grok-pager/src/settings`
- `crates/codegen/xai-grok-pager/src/slash/commands/mod.rs`
- `crates/codegen/xai-grok-pager/src/startup.rs`
- `crates/codegen/xai-grok-paths/src/lib.rs`
- `crates/codegen/xai-grok-plugin-marketplace/src/index.rs`
- `crates/codegen/xai-grok-plugin-marketplace/src/installer.rs`
- `crates/codegen/xai-grok-plugin-marketplace/src/lib.rs`
- `crates/codegen/xai-grok-sandbox/src/deny`
- `crates/codegen/xai-grok-sandbox/src/lib.rs`
- `crates/codegen/xai-grok-sandbox/src/profiles.rs`
- `crates/codegen/xai-grok-sandbox/src/types.rs`
- `crates/codegen/xai-grok-shell/README.md`
- `crates/codegen/xai-grok-shell/skills`
- `crates/codegen/xai-grok-shell/src/auth/device_code.rs`
- `crates/codegen/xai-grok-shell/src/auth/flow.rs`
- `crates/codegen/xai-grok-shell/src/auth/manager.rs`
- `crates/codegen/xai-grok-shell/src/auth/recovery.rs`
- `crates/codegen/xai-grok-shell/src/auth/storage.rs`
- `crates/codegen/xai-grok-shell/src/cli_models.rs`
- `crates/codegen/xai-grok-shell/src/extensions/mod.rs`
- `crates/codegen/xai-grok-shell/src/inspect/mod.rs`
- `crates/codegen/xai-grok-shell/src/leader/mod.rs`
- `crates/codegen/xai-grok-shell/src/mcp_doctor.rs`
- `crates/codegen/xai-grok-shell/src/plugin.rs`
- `crates/codegen/xai-grok-shell/src/sampling/mod.rs`
- `crates/codegen/xai-grok-shell/src/session/acp_session.rs`
- `crates/codegen/xai-grok-shell/src/session/acp_types.rs`
- `crates/codegen/xai-grok-shell/src/session/chat_persistence.rs`
- `crates/codegen/xai-grok-shell/src/session/commands.rs`
- `crates/codegen/xai-grok-shell/src/session/compaction.rs`
- `crates/codegen/xai-grok-shell/src/session/goal_orchestrator.rs`
- `crates/codegen/xai-grok-shell/src/session/goal_planner.rs`
- `crates/codegen/xai-grok-shell/src/session/goal_strategist.rs`
- `crates/codegen/xai-grok-shell/src/session/mod.rs`
- `crates/codegen/xai-grok-shell/src/util/config/load.rs`
- `crates/codegen/xai-grok-shell/src/util/config/mcp.rs`
- `crates/codegen/xai-grok-shell/src/util/config/permissions.rs`
- `crates/codegen/xai-grok-shell/src/util/config/resolve/features.rs`
- `crates/codegen/xai-grok-shell/src/util/config/resolve/mod.rs`
- `crates/codegen/xai-grok-shell/src/util/config/resolve/system_prompt.rs`
- `crates/codegen/xai-grok-shell/src/util/config/resolve/tool_approvals.rs`
- `crates/codegen/xai-grok-shell/src/util/hooks.rs`
- `crates/codegen/xai-grok-subagent-resolution/src/lib.rs`
- `crates/codegen/xai-grok-subagent-resolution/src/types.rs`
- `crates/codegen/xai-grok-tools/src/implementations/skills`
- `crates/codegen/xai-grok-tools/src/lib.rs`
- `crates/codegen/xai-grok-tools/src/registry/mod.rs`
- `crates/codegen/xai-grok-update/src/auto_update.rs`
- `crates/codegen/xai-grok-update/src/version.rs`
- `crates/codegen/xai-hooks-plugins-types/src`
- `crates/codegen/xai-ratatui-textarea/src`
- `crates/codegen/xai-tty-utils/src`
- `README.md`
- `rust-toolchain.toml`