grok skill

Grok Build CLI — Hermes Orchestration Guide

Delegate coding tasks to Grok Build (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

works, but the x.ai host is Cloudflare-walled in some environments. The npm path avoids that dependency entirely.

• Install (preferred): npm install -g @xai-official/grok
• The official installer curl -fsSL https://x.ai/cli/install.sh | bash also

~/.grok/auth.json. This uses your SuperGrok or X Premium+ subscription (no per-token API billing).

• Auth — SuperGrok / X Premium+ subscription (primary path):
• Run grok login once → opens a browser for OAuth → token cached in

headless smoke test: grok --no-auto-update -p "Say ok."

• Check sign-in state by looking for ~/.grok/auth.json, or run a cheap

directory (good for scratch/throwaway tasks).

• 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

CLAUDE.md, .claude/ (skills, agents, MCPs, hooks, rules), and the AGENTS.md family. Existing project context just works.

• Claude Code / AGENTS.md compatible with zero config — Grok auto-reads

API-key fallback (not the default for this user): Grok also supports

setting the XAIAPIKEY 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

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:

write_file). Snapshot only the relevant context into a temp file rather than dumping raw paths.

1. Prepare stable input files first with Hermes tools (read_file,

demand markdown only, no preamble.

1. Run Grok headless without --always-approve so it cannot auto-write, and

1. 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