Grok Build Documentation

Pages

1. OverviewWhat 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.
2. InstallationInstall and update the released grok binary on macOS, Linux, and Windows; PATH layout under ~/.grok/bin; version pin flags; verify with grok --version.
3. QuickstartFirst interactive session: launch grok, authenticate, send a prompt, use @ file attachments, cancel turns, and confirm tool output in the TUI scrollback.
4. AuthenticationBrowser 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.
5. SessionsSession lifecycle: create, resume, continue, fork, compact, export; persistence layout; /new /resume /compact; grok sessions subcommands and ID constraints.
6. Permissions and safetyTool authorization pipeline: PreToolUse hooks, allow/deny/ask rules, remembered grants, permission modes (including bypassPermissions/dontAsk), safe-bash defaults, and interaction with sandbox.
7. Project rules and memoryAGENTS.md discovery and precedence; cross-session memory (/flush, /dream, hybrid search); when rules inject into the system prompt versus when memory retrieval runs.
8. Configure GrokHow to set config.toml and pager.toml, precedence (CLI > env > user config > managed/requirements > defaults), feature flags, and grok inspect to dump resolved settings.
9. Custom modelsSelect models via -m and /model; configure BYOK and OpenAI-compatible or Ollama endpoints; per-model overrides; grok models listing and provider-neutral endpoint settings.
10. MCP serversRegister MCP servers in config.toml (stdio and HTTP), timeouts and env, enable/disable, OAuth-related MCP credentials, and grok mcp management commands.
11. SkillsSKILL.md package layout, discovery paths (.grok, .agents, .claude, .cursor), priority and ignore rules, slash-command surface, and config toggles for vendor skill trees.
12. PluginsInstall and trust plugins that bundle skills, commands, agents, hooks, MCP, and LSP; marketplace sources; plugin.json conventions; GROK_PLUGIN_ROOT and GROK_PLUGIN_DATA.
13. HooksLifecycle hooks (PreToolUse, PostToolUse, SessionStart, and peers): JSON discovery, shell vs HTTP runners, deny/allow results, environment variables, and safety patterns.
14. Headless modeNon-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.
15. Agent mode (ACP)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.
16. Sandbox profilesOS-level isolation profiles (workspace, read-only, strict, devbox, off), --sandbox flag, custom deny globs, Linux vs macOS enforcement differences for child network.
17. Subagents and personasSpawn and constrain child agents: agent types, personas, capability modes, isolation/worktree behavior, and headless Agent(...) denylist entries.
18. Plan modeStructured planning before edits: plan files, approval gates, mode entry/exit from the TUI, and how plan mode interacts with tools and permissions.
19. ThemingTUI appearance: /theme, pager.toml theme keys, color-support detection, screen modes (fullscreen/minimal), and terminal capability constraints.
20. CLI referenceTop-level grok commands and flags: default TUI, agent, login/logout, mcp, plugin, memory, models, sessions, inspect, setup, update, wrap, export, trace; shared runtime flags.
21. Configuration referenceSchema-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.
22. Slash commandsInteractive / commands for sessions, models, memory, hooks, plugins, themes, and more; pager vs shell builtins; skill-provided commands in the autocomplete menu.
23. Keyboard shortcutsTUI key bindings for prompt and scrollback focus, cancel, rewind, vim mode, mouse actions, and multi-key Escape behavior with timing constraints.
24. TroubleshootingTerminal support issues (tmux, SSH, truecolor, OSC 52 clipboard), color warnings, auth recovery, MCP startup failures, and diagnostics probes backed by the pager diagnostics module.
25. Build from sourceWorkspace 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.