​

Skill metadata

​

Reference: full SKILL.md

​

Grok Build CLI — Mibyan Orchestration Guide

​

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)

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

• 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

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

​

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

​

Session Continuation

# 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

1. Prepare stable input files first with Mibyan 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 ~/.mibyan/cache/scratch/current.md and ~/.mibyan/cache/scratch/inventory.md. Produce markdown only, no preamble. Output a clean note titled 'Cleanup Review'." --output-format plain

​

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 ~/.mibyan/cache/scratch/issue-78 main", workdir="~/project")
terminal(command="git worktree add -b fix/issue-99 ~/.mibyan/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="~/.mibyan/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="~/.mibyan/cache/scratch/issue-99", background=true, notify_on_complete=true)

# Monitor
process(action="list")

# After completion: push and open PRs
terminal(command="cd ~/.mibyan/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 ~/.mibyan/cache/scratch/issue-78", workdir="~/project")

​

Useful Subcommands & TUI Commands

​

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"

​

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 Mibyan’ xAI auth with the grok CLI’s auth. Mibyan’ 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 <name> when done.

​

Rules for Mibyans

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 <session> -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 Mibyan’ xAI auth carries over.
8. Report results to the user — summarize what Grok changed and what’s left.