Neura Market Logo
OptionalAutonomous AI AgentsVersion 0.1.1

Using Grok Build CLI with Hermes Agent for Autonomous Coding

Delegate coding to xAI Grok Build CLI (features, PRs).

Written by Neura Market from the official Hermes Agent documentation for Grok. Commands, paths, and version numbers are reproduced from the source unchanged.

Read the official documentation

Grok Build CLI Reference

This document covers the Grok Build CLI, an autonomous coding agent from xAI that operates through the Hermes terminal. It can read files, write code, run shell commands, spawn subagents, and manage git workflows. Use it for building features, refactoring, PR reviews, batch issue fixing, or any task where you would otherwise use codex or claude-code but want Grok.

Prerequisites

Before using the CLI, ensure the following are in place:

  • Installation: Install via npm (preferred) or curl.
    • npm: npm install -g @xai-official/grok
    • curl: curl -fsSL https://x.ai/cli/install.sh | bash
  • Authentication: Run grok login once. This opens a browser for OAuth and caches the token in ~/.grok/auth.json. Requires a SuperGrok or X Premium+ subscription.
  • Verify auth: Check ~/.grok/auth.json or run grok --no-auto-update -p "Say ok.". The literal grok -p "Say ok." is used for a quick one-shot query, while grok --no-auto-update -p "Say ok." is the preferred form for automation to skip update checks.
  • API-key fallback: Set the XAI_API_KEY environment variable if subscription auth is unavailable. This uses the api.x.ai endpoint.
  • No git repo required: The tool works without a git repo, but for PR or commit workflows use mktemp -d && git init.

Do not conflate Hermes' xAI auth with the grok CLI auth; they are separate. Prefer npm install over the curl installer to avoid the Cloudflare-walled x.ai host.

Configuration

The configuration file is ~/.grok/config.toml (not project-scoped). A .grok/config.toml file is not supported. Example configuration:

[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"

The permission_mode key supersedes the legacy approval_mode or yolo = true keys.

Modes of Operation

Grok Build operates in three modes: headless one-shot, interactive PTY (TUI), and as an ACP agent over JSON-RPC. The headless mode is preferred for automation.

Headless One-Shot (Preferred)

Use this for single-prompt tasks that run and exit. Ensure prerequisites are met (install, auth). Construct the command with -p (or --single) and the prompt. Always pass --no-auto-update in automation to skip background update checks and avoid potential unreachability.

terminal(command="grok --no-auto-update -p 'Add a dark mode toggle to settings'", workdir="/path/to/project", timeout=180)

Optionally add --output-format json for structured output and --always-approve for autonomous writes. Set workdir and timeout in the terminal call.

# 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)

Interactive PTY (Multi-Turn TUI)

For multi-turn interactions, launch a tmux session and send commands to it. Use pty=true in the terminal call.

# 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 using tmux capture-pane. The literal `tmux capture-pane -t -p -S -50` is the correct syntax for capturing the last 50 lines of the pane output.
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")

Use --no-alt-screen if the TUI alt-screen garbles captured output. Clean up tmux sessions with tmux kill-session -t when done.

Parameters

All parameters are optional unless noted.

  • -p, --single <prompt>: Send one prompt, run headless, exit. Required for headless mode.
  • -m, --model <model>: Choose a model.
  • -s, --session-id <uuid>: Assign a NEW valid UUID to a fresh conversation. Does NOT resume. Only valid with --resume/--continue when paired with --fork-session.
  • -r, --resume [<uuid>]: Resume an existing session by UUID (or 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 <format>: Output format: plain (default), json, or streaming-json.
  • --always-approve: Auto-approve all tool executions (autonomous mode). Required for autonomous builds; omit for read-only reviews.
  • --no-alt-screen: Run inline, no fullscreen TUI takeover.
  • --no-auto-update: Skip background update checks. Use in all automation.
  • --help: Show help.

The --full-auto and --yolo flags are not supported.

Session Management

Sessions allow you to continue conversations across terminal calls. Session IDs are UUIDs.

# 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)

Use --session-id to assign a NEW UUID; it does NOT resume. Use -r, --resume [] to resume by UUID. Use -c, --continue to continue the most recent session.

Background Mode (Long Tasks)

For long-running tasks, start headless with background=true, notify_on_complete=true. Monitor with process and kill if needed.

# 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>")

Read-Only Audit to Markdown Note

Prepare stable input files using Hermes tools (read_file, write_file). Run Grok headless WITHOUT --always-approve. Demand markdown only, no preamble in the prompt. Save stdout directly to 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

For document rewrites, demand: "Return ONLY the full revised markdown document. No intro, no explanation, no code fences. Start immediately with '# Title'." to avoid getting a summary instead of the full file. Verify the first lines with read_file() before overwriting the destination.

PR Review (Headless)

Change to the repo directory and pipe the git diff to Grok.

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)

Set timeout appropriately.

Clone-to-Temp Review (Safe)

Create a temp directory, clone the repo, checkout the PR, run Grok headless with pty=true, and post the review.

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, launch Grok headless in each with background=true, notify_on_complete=true, monitor, push, create PRs, and cleanup.

# 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")

Context Files

Grok Build auto-reads CLAUDE.md, .claude/ (skills, agents, MCPs, hooks, rules), and the AGENTS.md family of files. These provide project context and instructions.

In-Session Commands

While in the interactive TUI, you can use these commands:

  • /model: Switch models.
  • /always-approve: Toggle auto-approval.
  • /plan: Generate a plan.
  • /context: Show current context.
  • /compact: Compact the conversation.
  • /resume: Resume a session.
  • /sessions: List sessions.
  • /fork: Fork the current session.
  • /usage: Show usage.
  • /quit: Exit the session.
  • /logout: Log out.
  • /login: Log in.
  • Shift+Tab: Cycle through options.

Other CLI Commands

  • grok -p "query": Quick one-shot query. The literal claude -p is the equivalent command for Claude Code, but Grok uses grok -p.
  • grok logout: Log out.
  • grok inspect: Inspect configuration.
  • grok agent stdio: Run as an ACP agent over stdio.
  • grok update: Update the CLI.

Constraints and Caveats

  • Auth is subscription-gated: requires SuperGrok or X Premium+ subscription.
  • Always pass --no-auto-update in automation.
  • --always-approve is required for autonomous builds; omit for read-only reviews.
  • Headless -p skips TUI dialogs; TUI needs pty=true and tmux for monitoring.
  • Use --no-alt-screen if TUI alt-screen garbles captured output.
  • No git repo needed, but for PR/commit workflows use mktemp -d && git init.
  • Clean up tmux sessions with tmux kill-session -t when done.
  • For document rewrites, demand full file output to avoid summaries.
  • Session IDs are UUIDs; --session-id assigns a NEW UUID, does NOT resume.
  • Config file is ~/.grok/config.toml (not project-scoped).
  • permission_mode supersedes legacy approval_mode / yolo = true keys.

Failure Modes

  • Login fails or no ~/.grok/auth.json: subscription may be inactive.
  • Headless run stalls without --always-approve due to tool-approval prompts.
  • x.ai or storage.googleapis.com unreachable in some environments.
  • Loose "rewrite this" prompt returns change summary instead of full file.
  • TUI output garbled if captured without --no-alt-screen.
  • tmux sessions left running if not killed explicitly.

Capabilities Summary

  • Read files
  • Write code
  • Run shell commands
  • Spawn subagents
  • Manage git workflows
  • Run in interactive TUI, headless (-p), or as ACP agent over JSON-RPC
  • Auto-reads CLAUDE.md, .claude/ (skills, agents, MCPs, hooks, rules), and AGENTS.md family
  • Works without a git repo
  • Supports x_search for web search

Skills the docs pair this with

More Autonomous AI Agents skills

Antigravity CliOperate the Antigravity CLI (agy): plugins, auth, sandbox.BlackboxDelegate coding tasks to the Blackbox AI multi-model CLI.Claude CodeDelegate coding to Claude Code CLI (features, PRs).CodexDelegate coding to OpenAI Codex CLI (features, PRs).Computer UseDrive the desktop in the background without stealing focus.Hermes AgentUse, configure, theme, extend, and orchestrate Hermes Agent.