Using Grok Build CLI with Hermes Agent for Autonomous Coding

This guide covers how to delegate coding tasks to xAI's Grok Build CLI through the Hermes Agent runtime. Grok is an autonomous coding agent that can read files, write code, run shell commands, spawn subagents, and manage git workflows. It runs in three modes: an interactive TUI, headless (one-shot prompts), and as an ACP agent over JSON-RPC. You would reach for this when you want an AI agent to build features, refactor code, review pull requests, or batch-fix issues, and you prefer Grok over alternatives like Codex or Claude Code.

What it does

Grok Build CLI, orchestrated by Hermes Agent, lets you automate software development tasks that would normally require a human developer. You give it a natural language instruction, and it autonomously reads your project files, writes code, runs shell commands, and commits changes. The Hermes Agent handles the orchestration: it launches Grok in the right working directory, passes the prompt, monitors progress, and collects results. This is useful for CI/CD pipelines, automated refactoring, PR reviews, and any repetitive coding task where you want to offload the work to an AI.

Before you start

Prerequisites

• Install Grok CLI (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.

• Authentication: You need a SuperGrok or X Premium+ subscription. Run grok login once to open a browser for OAuth. The token is cached in ~/.grok/auth.json. Check sign-in state by looking for that file, or run a cheap headless smoke test: grok --no-auto-update -p "Say ok."

• No git repo required: Unlike Codex, Grok runs fine outside a git directory, which is useful for scratch or throwaway tasks.

• Claude Code / AGENTS.md compatible: 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	Send one prompt, run headless, exit
-m, --model	Choose a model
-s, --session-id	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 []	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	Cap the maximum number of agent turns
--cwd	Set the working directory
--output-format	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 /tmp/current.md and /tmp/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 /tmp/issue-78 main", workdir="~/project")
terminal(command="git worktree add -b fix/issue-99 /tmp/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="/tmp/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="/tmp/issue-99", background=true, notify_on_complete=true)

# Monitor
process(action="list")

# After completion: push and open PRs
terminal(command="cd /tmp/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 /tmp/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 , /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)

[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.
7. Use --no-alt-screen if you run the TUI inline and the fullscreen alt-screen takeover garbles captured output.
8. No git repo needed, but for PR/commit workflows you still want one, use mktemp -d && git init for scratch commit tasks.
9. Clean up tmux sessions with tmux kill-session -t when done.

Rules for Hermes Agents

1. Prefer headless -p for single tasks, cleanest integration, structured output via --output-format json.
2. Always set workdir (or --cwd) so Grok targets the right project.
3. Pass --no-auto-update in every automated invocation.
4. Use --always-approve only when Grok should write autonomously; omit it for read-only reviews and audits.
5. Background long tasks with background=true, notify_on_complete=true and monitor via the process tool.
6. Use tmux for multi-turn interactive work and monitor with tmux capture-pane -t -p -S -50.
7. Verify auth before relying on it, check ~/.grok/auth.json or run a cheap grok -p "Say ok." smoke test; don't assume Hermes' xAI auth carries over.
8. Report results to the user, summarize what Grok changed and what's left.

When not to use it

If you do not have a SuperGrok or X Premium+ subscription, or if your environment cannot reach the npm registry or the x.ai host for installation, this skill will not work. Also, if you need a coding agent that works entirely offline, Grok is not the right choice. For tasks that require deterministic, non-AI automation, a traditional script or CI pipeline is more appropriate.

Limits and gotchas

• The --session-id flag assigns a new UUID to a fresh conversation; it does not resume an existing one. Use --resume or --continue for that.
• The grok update command requires access to the x.ai host, which may be blocked in some environments.
• The --no-auto-update flag is hidden from --help but still works.
• The config file is global only (~/.grok/config.toml); project-scoped .grok/config.toml is not supported.

What pairs with this

This skill is the third sibling to codex and claude-code. The orchestration pattern is nearly identical. If you are already using those skills, you can apply the same Hermes Agent patterns to Grok. The hermes-agent skill itself provides the runtime that orchestrates these coding agents.