grok

# Grok Build CLI — Hermes Orchestration Guide Delegate coding tasks to [Grok Build](https://docs.x.ai/build/overview) (xAI's autonomous coding agent CLI, the `grok` command) via the Hermes terminal. Grok can read files, write code, run shell commands, spawn subagents, and manage git workflows. It runs three ways: an interactive TUI, **headless** (`-p`), and as an **ACP agent** over JSON-RPC. This is the third sibling to `codex` and `claude-code`. The orchestration pattern is nearly identical — **prefer headless `-p` for one-shots**, use a PTY for interactive sessions. ## When to use - Building features - Refactoring - PR reviews - Batch issue fixing - Any task where you'd otherwise reach for Codex / Claude Code but want Grok ## Prerequisites - **Install (preferred):** `npm install -g @xai-official/grok` - The official installer `curl -fsSL https://x.ai/cli/install.sh | bash` also works, but the `x.ai` host is Cloudflare-walled in some environments. The npm path avoids that dependency entirely. - **Auth — SuperGrok / X Premium+ subscription (primary path):** - Run `grok login` once → opens a browser for OAuth → token cached in `~/.grok/auth.json`. This uses your **SuperGrok or X Premium+** subscription (no per-token API billing). - Check sign-in state by looking for `~/.grok/auth.json`, or run a cheap headless smoke test: `grok --no-auto-update -p "Say ok."` - In the TUI, `/logout` signs out and `/login` (or relaunching) signs back in. - **No git repo required** — unlike Codex, Grok runs fine outside a git directory (good for scratch/throwaway tasks). - **Claude Code / AGENTS.md compatible with zero config** — Grok auto-reads `CLAUDE.md`, `.claude/` (skills, agents, MCPs, hooks, rules), and the `AGENTS.md` family. Existing project context just works. > **API-key fallback (not the default for this user):** Grok also supports > setting the `XAI_API_KEY` environment variable for pay-as-you-go billing > via `api.x.ai`. Only use > this if `grok login` / SuperGrok auth is unavailable. The subscription path > (`grok login`) is the intended setup here. ## Two Orchestration Modes ### Mode 1: Headless (`-p`) — Non-Interactive (PREFERRED) Runs a one-shot task, prints the result, and exits. No PTY, no interactive dialogs to navigate. This is the cleanest integration path — the analog of `claude -p` and `codex exec`. ``` terminal(command="grok --no-auto-update -p 'Add a dark mode toggle to settings'", workdir="/path/to/project", timeout=180) ``` Always pass `--no-auto-update` in automation to skip background update checks. **When to use headless:** - One-shot coding tasks (fix a bug, add a feature, refactor) - CI/CD automation and scripting - Structured output parsing with `--output-format json` - Any task that doesn't need multi-turn conversation ### Mode 2: Interactive PTY — Multi-Turn TUI Sessions The TUI is a fullscreen, mouse-interactive app. Drive it with `pty=true`. For robust monitoring/input use tmux (same pattern as the `claude-code` skill). ``` # Launch in a tmux session for capture-pane monitoring terminal(command="tmux new-session -d -s grok-work -x 140 -y 40") terminal(command="tmux send-keys -t grok-work 'cd /path/to/project && grok' Enter") # Wait for startup, then send a task terminal(command="sleep 5 && tmux send-keys -t grok-work 'Refactor the auth module to use JWT' Enter") # Monitor progress terminal(command="sleep 15 && tmux capture-pane -t grok-work -p -S -50") # Exit when done terminal(command="tmux send-keys -t grok-work '/quit' Enter && sleep 1 && tmux kill-session -t grok-work") ``` **Tip for headless-but-inline output:** if you want TUI-style output without the fullscreen alt-screen takeover (e.g. for cleaner logs), add `--no-alt-screen`. For pure automation, headless `-p` is still cleaner than the TUI. ## Headless Deep Dive ### Common Flags | Flag | Effect | |------|--------| | `-p, --single <PROMPT>` | Send one prompt, run headless, exit | | `-m, --model <MODEL>` | Choose a model | | `-s, --session-id <UUID>` | Assign a **NEW** valid UUID to a fresh conversation (must not already exist). Does **not** resume — use `--resume`/`--continue` for that. Only valid with `--resume`/`--continue` when paired with `--fork-session` | | `-r, --resume [<UUID>]` | Resume an existing session by its UUID (or the most recent if omitted) | | `-c, --continue` | Continue the most recent session in the current directory | | `--fork-session` | When resuming, create a new session ID instead of reusing the original | | `--max-turns <N>` | Cap the maximum number of agent turns | | `--cwd <PATH>` | Set the working directory | | `--output-format <FMT>` | `plain` (default), `json`, or `streaming-json` | | `--always-approve` | Auto-approve all tool executions (the `--full-auto` / `--yolo` equivalent) | | `--no-alt-screen` | Run inline, no fullscreen TUI takeover | | `--no-auto-update` | Skip background update checks (use in all automation; hidden from `--help` but still works) | ### Output Formats - `plain` — human-readable text (default) - `json` — one JSON object at the end of the run (parse the result cleanly) - `streaming-json` — newline-delimited JSON events as they arrive ``` # Structured result for parsing terminal(command="grok --no-auto-update -p 'List all TODO comments in src/' --output-format json", workdir="/project", timeout=120) # Auto-approve for autonomous building terminal(command="grok --no-auto-update --always-approve -p 'Refactor the database layer and run the tests'", workdir="/project", timeout=300) ``` ### Background Mode (Long Tasks) ``` # Start headless in background terminal(command="grok --no-auto-update --always-approve -p 'Refactor the auth module'", workdir="/project", background=true, notify_on_complete=true) # Returns session_id # Monitor process(action="poll", session_id="<id>") process(action="log", session_id="<id>") # Kill if needed process(action="kill", session_id="<id>") ``` For an interactive (TUI) background session, use `pty=true` + tmux and monitor with `tmux capture-pane`, exactly like the `claude-code` / `codex` skills. ### Session Continuation Sessions are keyed by **UUID**, not by name. `--session-id` assigns a *new* UUID to a fresh run (it does **not** resume); `--resume` takes an existing session's UUID (or omit the value to resume the most recent). ``` # Start a session with a self-assigned UUID (must be a valid, unused UUID) SID=$(uuidgen) terminal(command="grok --no-auto-update -s $SID -p 'Start refactoring the database layer' --always-approve", workdir="/project", timeout=240) # Resume that exact session later by its UUID terminal(command="grok --no-auto-update -r $SID -p 'Now add connection pooling' --always-approve", workdir="/project", timeout=180) # Or just continue the most recent session in this directory (no UUID needed) terminal(command="grok --no-auto-update -c -p 'What did you change last time?'", workdir="/project", timeout=60) ``` ## Read-Only Audit → Markdown Note Pattern To have Grok review local artifacts and return a clean markdown note (for Obsidian or a repo) without mutating anything: 1. Prepare stable input files first with Hermes tools (`read_file`, `write_file`). Snapshot only the relevant context into a temp file rather than dumping raw paths. 2. Run Grok headless **without** `--always-approve` so it cannot auto-write, and demand `markdown only, no preamble`. 3. Save Grok's stdout straight into the destination note with `write_file()`. ``` grok --no-auto-update -p "Read ~/.hermes/cache/scratch/current.md and ~/.hermes/cache/scratch/inventory.md. Produce markdown only, no preamble. Output a clean note titled 'Cleanup Review'." --output-format plain ``` **Pitfall (same as Claude Code):** for document rewrites, a loose "rewrite this" prompt may return a change summary instead of the full file. Instead: pipe the file in, and demand `Return ONLY the full revised markdown document. No intro, no explanation, no code fences. Start immediately with '# Title'.` Verify the first lines with `read_file()` before overwriting the destination. ## PR Review Patterns ### Quick Review (Headless) ``` terminal(command="cd /path/to/repo && git diff main...feature-branch | grok --no-auto-update -p 'Review this diff for bugs, security issues, and style problems. Be thorough.'", timeout=120) ``` ### Clone-to-temp Review (safe, no repo mutation) ``` terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && grok --no-auto-update -p 'Review the changes vs origin/main. Check bugs, security, race conditions, missing tests.'", pty=true, timeout=300) ``` ### Post the review ``` terminal(command="gh pr comment 42 --body '<review text>'", workdir="/path/to/repo") ``` ## Parallel Issue Fixing with Worktrees ``` # Create worktrees terminal(command="git worktree add -b fix/issue-78 ~/.hermes/cache/scratch/issue-78 main", workdir="~/project") terminal(command="git worktree add -b fix/issue-99 ~/.hermes/cache/scratch/issue-99 main", workdir="~/project") # Launch Grok headless in each (background) terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #78: <description>. Commit when done.'", workdir="~/.hermes/cache/scratch/issue-78", background=true, notify_on_complete=true) terminal(command="grok --no-auto-update --always-approve -p 'Fix issue #99: <description>. Commit when done.'", workdir="~/.hermes/cache/scratch/issue-99", background=true, notify_on_complete=true) # Monitor process(action="list") # After completion: push and open PRs terminal(command="cd ~/.hermes/cache/scratch/issue-78 && git push -u origin fix/issue-78") terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'") # Cleanup terminal(command="git worktree remove ~/.hermes/cache/scratch/issue-78", workdir="~/project") ``` ## Useful Subcommands & TUI Commands | Command | Purpose | |---------|---------| | `grok` | Start the interactive TUI | | `grok -p "query"` | Headless one-shot | | `grok login` / `grok logout` | Sign in / out (SuperGrok / X Premium+ OAuth) | | `grok inspect` | Show what Grok discovered in cwd: config sources, instructions, skills, plugins, hooks, MCP servers | | `grok agent stdio` | Run as an ACP agent over JSON-RPC (for IDE/tool integration) | | `grok update` | Update the CLI (needs the `x.ai` host; skip in automation) | TUI slash commands (interactive only): `/model <name>`, `/always-approve`, `/plan`, `/context`, `/compact`, `/resume`, `/sessions`, `/fork`, `/usage`, `/quit`. `Shift+Tab` cycles session modes (including Plan mode, which blocks write tools except the session plan file). ## Config (`~/.grok/config.toml`) ```toml [cli] auto_update = false # skip background update checks persistently [ui] permission_mode = "ask" # or "always-approve" to skip tool prompts by default [models] default = "grok-build-0.1" ``` Put global preferences in `~/.grok/config.toml` (not project-scoped `.grok/config.toml`). `permission_mode` supersedes the legacy `approval_mode` / `yolo = true` keys. ## Pitfalls & Gotchas 1. **Auth is subscription-gated.** `grok login` requires a SuperGrok or X Premium+ subscription. If login fails or there's no `~/.grok/auth.json`, confirm the subscription is active before falling back to `XAI_API_KEY`. 2. **Don't conflate Hermes' xAI auth with the `grok` CLI's auth.** Hermes' `x_search` runs on its own xAI OAuth; the standalone `grok` CLI has a separate token in `~/.grok/auth.json`. A working `x_search` does NOT mean `grok` is logged in. 3. **Always pass `--no-auto-update` in automation** — otherwise Grok phones home for update checks (and `x.ai`/`storage.googleapis.com` may be unreachable). 4. **Prefer npm install over the curl installer** — `npm install -g @xai-official/grok` avoids the Cloudflare-walled `x.ai` host. 5. **`--always-approve` is the autonomous-build switch.** Without it, headless runs may stall waiting on tool-approval prompts. Omit it deliberately for read-only review/audit work so Grok can't mutate files. 6. **Headless `-p` skips TUI dialogs**; the TUI needs `pty=true` (+ tmux for monitoring), just like Claude Code.