oh-my-grok (OMG)

Start Grok stronger — then let OMG own the workflow, evidence, and verified completion.
_{Hero art: original AI-assisted mascot for oh-my-grok (ImL1s, 2026) · MIT with the repo · not affiliated with OMC/OMX/OmO}

English | 简体中文 | 繁體中文

Multi-agent orchestration for Grok Build.
Sibling of oh-my-claudecode (OMC), oh-my-codex (OMX), and oh-my-openagent (OmO) — same orchestration idea, Grok-native runtime.

Unofficial community plugin — not affiliated with xAI or the OMC/OMX/OmO maintainers.

Don't learn every Grok flag. Use omg + skills: clarify → plan → execute → verify.

Docs (EN): Skills catalog · Autopilot · Security model · Agent model routing · Docs index · Changelog

文件（繁中）: Skills 目錄 · Autopilot · 安全模型 · Agent 模型路由（投影） · 英文 canonical · 文件索引 · README 繁中

文档（简体）: Skills 目录 · Autopilot · 安全模型 · Agent 模型路由（投影） · 英文 canonical · 文档索引 · README 简体

OMG does not replace Grok Build.

Workers fan out only via Grok spawn_subagent (depth 1). No Rust fork of grok-build.
tmux: host session shell for bare omg / omg --madmax (interactive and break-glass launch; OMG_LAUNCH_POLICY / --direct / --tmux), plus the tmux team plane (omg team, default on; kill switch OMG_DISABLE_TMUX_TEAM=1; legacy OMG_EXPERIMENTAL_TMUX_TEAM=0 disables). Zero-config panes are grok only; optional --routing enables multi-CLI executor panes (codex/agy/cursor/gemini) with role floors. Isolation is integration isolation (worktree ownership + seal + integrate), not an execution sandbox — see the per-provider posture table in docs/security-model.md.
Scope honesty: OMG owns repository workflows, recovery, project services, and release contracts. Grok-native /create-workflow/Rhai and public dashboard integration remain optional_unclaimed; LSP/MCP registration is not host-health proof, and the team plane is integration isolation rather than an execution sandbox.

Version: 0.8.0 · License: MIT

Requirements: Grok Build CLI (grok on PATH) · Python 3.11+

Host compatibility: Original Grok Build is the required, first-class baseline host. OMG installs and runs ordinary agents, skills, workflows, evidence, and acceptance with Medley absent. Medley is an optional compatible host; installing OMG does not install Medley, and Medley is never a hard dependency. Grok-side omg agents list|explain policy inspect is shipped; Medley exact/candidate/receipt consumption remains unsupported on stock Grok Build (ImL1s/medley#287). Current omg doctor reports current host/session capabilities plus the routing capability registry; it does not treat missing Medley as an install failure. External Team CLI executors (--routing) remain separate optional tools. Details: docs/architecture/agent-model-routing.md.

OMG has two surfaces: Grok plugin (skills/agents/hooks) + omg CLI (state, accept, verified). You need both for the full product.

The bootstrap resolves GitHub latest once, validates its semantic tag, then downloads the archive and SHA256SUMS only from that immutable release tag. It verifies before extraction, switches the plugin + CLI transactionally, runs an install-time doctor gate, and rolls back a failed switch.

Integrity failures (package digest, stage/CLI/plugin pointers, owned globals, checksum mismatch, malformed receipt) still fail the gate and roll back. Host coexistence WARNs — foreign orch plugins visible in grok inspect, Claude Code hooks / CLAUDE.md markers — do not block a checksum-verified release install; the receipt may record completed_with_warning. Interactive omg doctor --strict still promotes those coexistence risks to FAIL.

# 0) Host
curl -fsSL https://x.ai/cli/install.sh | bash
# docs: https://github.com/xai-org/grok-build · https://x.ai/cli

# 1) Full OMG product from the latest immutable GitHub release
curl -fsSL https://raw.githubusercontent.com/ImL1s/oh-my-grok/main/scripts/install.sh | bash
omg --version

# 2) Wire a project
cd /path/to/your-project
omg setup
omg doctor --strict

Install success means integrity passed (receipt may be installed or completed_with_warning). Interactive omg doctor --strict can still exit 1 on coexistence WARNs — that is expected and unchanged.

The transaction installs to a stable, immutable stage and writes an install receipt. The underlying plugin switch installs the global PreToolUse soft-gate under $GROK_HOME/hooks/ — a self-contained standalone (omg_pretool_deny_standalone.py, launched python3 -I -S … || true), not a checkout-path script (plugin-bundled PreToolUse alone has been insufficient in live sessions; a checkout-path hook under TCC-protected ~/Documents bricked every tool in other workspaces — see docs/security-model.md).

Use this when you want to choose and inspect exact GitHub bytes. Both public assets must come from the same tag.

TAG=v0.8.0
curl -fLO "https://github.com/ImL1s/oh-my-grok/releases/download/${TAG}/oh-my-grok-0.8.0.tar.gz"
curl -fLO "https://github.com/ImL1s/oh-my-grok/releases/download/${TAG}/SHA256SUMS"
shasum -a 256 -c SHA256SUMS
curl -fsSLo install.sh "https://raw.githubusercontent.com/ImL1s/oh-my-grok/${TAG}/scripts/install.sh"
bash install.sh --offline \
  --archive ./oh-my-grok-0.8.0.tar.gz --checksums ./SHA256SUMS \
  --source-tag "${TAG}"
omg doctor --strict

Contributor checkout install remains available: clone a tag to a stable path, run ./scripts/install-plugin.sh, then link bin/omg. Editable pipx/pip is development-only because the full plugin also needs root siblings such as skills/, agents/, hooks, and templates.

grok plugin install ImL1s/oh-my-grok --trust
# better pin: grok plugin install ImL1s/oh-my-grok@v0.8.0 --trust

This installs skills/agents from GitHub. It does not put omg on PATH and does not guarantee the global soft-gate. Every omg … command in this README (including omg setup / omg doctor in the smoke steps below) requires the Full install — plugin-only gives you in-session skills only. Prefer Full install unless that is all you need.

Why omg update, not git pull alone: grok plugin install copies a frozen snapshot into ~/.grok/installed-plugins/; a bare git pull leaves the loaded plugin stale, and for a local-path install both grok plugin install (re-run) and grok plugin update are no-ops. Release receipts and unprovable development installs refresh via the verified stage scripts/install.sh release transaction. Clean development checkouts still fast-forward + install-plugin.sh. Contributor root= checkouts use install-plugin.sh (uninstall + reinstall same-path). omg doctor flags version/enabled/installed-content drift so you can't silently run an old copy.

omg setup scaffolds project files (.omg/, AGENTS fragment) and installs the global guidance contract $GROK_HOME/rules/omg.md (skip with --no-global-rules) and the global PreToolUse soft-gate $GROK_HOME/hooks/ (skip with --no-global-hook; repair anytime with omg install-hook). It does not install the plugin itself.

Recovery: a grok session already bricked by an old checkout-path hook can't run omg through its blocked terminal. From any plain shell: python3 -m omg_cli.hook_install (repairs it), or rm "${GROK_HOME:-$HOME/.grok}/hooks/omg-pretool-deny.json" to disable the soft-gate, then restart grok.

External-CLI diagnosis: v0.7.2 intentionally denies direct provider execution such as claude --version, but allows passive discovery/inspection such as which claude, command -v claude, and strings <provider-path>. If a simple passive command is denied, run omg doctor; if it reports global-hook drift, repair the hook with python3 -m omg_cli.hook_install. Do not create a persistent bypass or export OMG_ALLOW_EXTERNAL_CLI in a parent shell. See the canonical security contract and 2026-07-28 audit.

Smoke after install:

omg doctor
omg ulw "noop" --dry-run

That’s enough to start. Everything below is the default spine and reference.

This is the Grok-native equivalent of OMC's ~/.claude/CLAUDE.md / OMX's ~/.codex/AGENTS.md. omg setup writes an always-loaded operating contract to ~/.grok/rules/omg.md (Grok scans $GROK_HOME/rules/*.md every session). It is injected non-destructively: a bounded <!-- OMG:START -->…<!-- OMG:END --> block that re-setup reconciles in place, preserving any USER:OMG:POLICY block you add and a source-hash for drift detection. omg doctor reports its status (missing / version / hand-edit / corrupt).

Verify it loaded: grok inspect lists ~/.grok/rules/omg.md (global, …tokens). Because Grok's non-PreToolUse hooks are passive (their stdout is ignored — no additionalContext injection), keyword routing lives in this rules file's <workflow_routing> section, not in a hook.

When the task is non-trivial, prefer this spine (OMX-style, Grok-native):

1. omg interview start "…"     # clarify when vague  (or skill omg-deep-interview)
2. omg ralplan "…"             # plan consensus only — no implementation
3. omg ulw / omg ralph / omg autopilot …   # execute
4. omg accept --yes            # only path that may set verified (CLI stamp + process token)
   # or: omg autopilot complete --run RUN  (same-process accept+verify)

QA clean ≠ verified. UltraQA (omg qa) can go green without promoting the run.

UltraQA / accept tips (v0.3.2+):

• Freeze only allowlisted commands (python3 -m pytest …, project .py, true/false). Illegal basenames (grep, test, omg, python -c) fail at freeze with a tip — not only at run.
• Quote pytest markers: python3 -m pytest -q -m 'not live' (unquoted -m not live is auto-coalesced when possible).
• After clean UltraQA, prd.json is optional — omg accept / omg autopilot complete materialize it from clean scenarios (never overwrites an existing operator PRD).
• If omg accept already set verified, omg autopilot complete short-circuits (syncs autopilot_phase, no second full acceptance).

OMG has 16 skills. Full catalog with triggers, examples, and CLI twins:
→ docs/skills.md · index: docs/README.md

Many flows have both a skill playbook and a CLI subcommand (unlike OMC, where autopilot/ralph/ulw are skill-only).
Shared HARD RULES: spawn only via Grok; only CLI may set verified.

Priority if several match: cancel → ralplan → autopilot → ultragoal → ralph → ulw.

Vague idea     → deep-interview → ralplan → autopilot (or ralph / ulw)
Parallel fix   → ultrawork → integrate → accept
Must finish    → ralph
Full chat E2E  → autopilot   (+ "continue" if turn ends)
Multi-day stories → ultragoal + per-story ralph/ulw
After code     → dual-review → ultraqa → accept / autopilot complete

You:  autopilot 實作功能 X（含測試）
      # or: /oh-my-grok:omg-autopilot …
Grok: omg autopilot start "…" → … phases … → omg autopilot complete
You:  （中斷時）continue · omg autopilot status --run RUN

interview → ralplan → implement → review → qa → acceptance → verified

Deep guide: docs/autopilot.md · skill: skills/omg-autopilot/SKILL.md

1. Fan-out only via Grok spawn_subagent (depth = 1; children do not spawn).
2. Never use claude / codex / omc team / agy / cursor-agent as default workers (advisors are opt-in via omg ask).
3. Grok tool names: read_file, search_replace, run_terminal_command, spawn_subagent, grep, list_dir, …
4. Only omg CLI may set passes / verified under .omg/state/. Agents write proposals under .omg/artifacts/.
5. Cancel with omg cancel — never self-matching pkill -f.

Primary isolation is capability_mode (read-write implementers / read-only critic-verifier; no Execute for workers).
PreToolUse deny is fail-open soft-guard — not a sandbox. Details: docs/security-model.md.

The supported external-advisor path is omg ask. Its broker sets OMG_ALLOW_EXTERNAL_CLI=1 only in the fixed-argv child process; the variable is not a supported operator escape hatch for a parent shell or project environment.

omg {setup,doctor,update,uninstall,note,state,cancel,resume,wiki,hud,lsp,
     session,recover,memory,tracker,compact,notify,native-status,workflow,
     capabilities,parity,interview,goal,accept,integrate,worker,team,review,qa,
     autopilot,ulw,ralph,ralplan,ask,pipeline,dual-review,mcp-server,mcp-install} ...

OMX-aligned entry. Bare launch stays at safe defaults; --madmax is break-glass consent.

omg                                  # interactive grok (tmux when eligible)
omg "fix the failing tests"
omg --madmax                         # full-open + new tmux session + attach
omg --madmax "fix the failing tests"
omg --direct …                       # never wrap tmux
omg --tmux …                         # require tmux (fail closed if missing)
# OMG_LAUNCH_POLICY=auto|direct|tmux|detached-tmux  (CLI --direct/--tmux win)
# already inside $TMUX → grok in current pane
# auto policy: headless (-p / --single / --prompt-file) → no tmux (stdout preserved)
# explicit --tmux is strict even for headless (fail closed if tmux/TTY unavailable)
# Arguments after `--` are opaque. Root --yolo is mode elevation only — not a madmax alias.

omg setup && omg doctor

omg ralplan "consensus plan for auth refactor" --safe
omg ulw "parallelize the flaky test fix" --dry-run
omg ralph "ship the auth migration" --max-iter 5

# Autopilot CLI (skill omg-autopilot drives the same machine in-session)
omg autopilot start "ship feature X with tests"
omg autopilot start "ship feature X" --skip-interview
omg autopilot status --run RUN
omg autopilot complete --run RUN

omg worker own --run RUN --tasks-json '[{"task_id":"t1","owned_files":["a.py"]}]'
omg worker prepare --task t1 --run RUN
omg worker seal --task t1 --run RUN
omg worker join --run RUN
omg integrate --run RUN

omg accept --yes
omg accept --review --yes
omg state --human
omg cancel

{
  "version": 1,
  "goal": "...",
  "stories": [
    {"id": "s1", "title": "...", "commands": [["pytest", "tests/test_foo.py", "-q"]]}
  ],
  "global_commands": [["python3", "-m", "pytest", "tests/", "-q"]]
}

Floors always deny: agent CLIs, shells, npx, python -c/-e, dangerous git/make/go forms.
set_verified needs CLI stamp + matching manifest sha + in-process acceptance token — forged {passed:true} is rejected.

Envelopes under .omg/artifacts/ulw-results/<run_id>/. Strict-v2 ULW requires ownership manifest + complete join before integrate. Does not set verified.

draft → critic → revise → verifier → accepted | failed

Accepted only with whole-word APPROVE in verifier artifact. Never implements product code.

User / Grok session  →  skills + agents
         │
         ├─► omg CLI (single-writer: status / accept / integrate / verified)
         └─► hooks (fail-open PreToolUse soft-guard + event spool)

.omg/state/runs/<run-id>/     CLI authority
.omg/artifacts/               proposals + ULW envelopes
.omg/ultragoal/               goal ledger (when used)
.omg/wiki/                    project markdown wiki
.omg/state/RESUME.md          one-shot continuity pack written by `omg resume`
.omg/workflows/registry/      immutable repository workflow definitions
.omg/memory/facts.json        redacted deterministic project facts
.omg/state/recovery/          immutable bounded recovery packs

Full usage for every skill (triggers · CLI · examples): docs/skills.md.

Agents: omg-orchestrator, omg-executor, omg-critic, omg-verifier, omg-code-reviewer, omg-architect, omg-qa-tester, omg-analyst — see docs/skills.md § Agents.

cd /path/to/oh-my-grok
python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install -r requirements-dev.txt

PYTHONPATH=. python3 -m pytest -q -m "not live"
grok plugin validate .
./bin/omg doctor
./scripts/smoke.sh

Do not claim production isolation from unit green alone. See docs/research/test-matrix.md.

Full dual-review ship bar (C1–C9) is complete. Recent lines:

• v0.2.x: acceptance policy, run mutex, ULW integrate, ralplan FSM, worker prepare/seal, pipeline order, live suite.
• 2026-07-20 core-purpose parity: evidence stamps, session lease, interview, goal ledger + repair, ULW ownership/join, hash-bound review, UltraQA, strict autopilot; destination gates; CLI acceptance authority for verified.
• v0.2.6: omg --madmax full-open host launch in tmux; OSS install dual-track + release protocol; CI smoke.
• v0.6.0: versioned repository workflows; exact session routes and bounded recovery; project memory, tracker, compaction and outbound notifications; plugin MCP/LSP manifests; immutable GitHub-release installation and release readback.
• v0.7.4: team scale/resume crash recovery — generation-scoped WAL, fail-closed window ownership readback, pending identity-receipt lifecycle gates, receipt-bound remove recovery, meta result-loss adopt; hermetic tests without live tmux. Integration isolation only (not an execution sandbox).
• v0.7.2+ team plane: default-on omg team (kill OMG_DISABLE_TMUX_TEAM); process-ready + P0′ API + doctor; LIVE_TEAM_SMOKE_OK local 2026-07-30; integration isolation only.
• v0.5.0: fail-closed gate and global-hook hardening; multi-CLI tmux team plane (then experimental-gated) with integration isolation; in-session MCP server; local LSP probe; editable packaging.
• v0.4.2: omg worker seal --all — leader batch seal (fail-closed; valid head_sha); local-path installer force-refresh (uninstall+reinstall).
• v0.4.1: backlog polish (omg note --prune, installed-snapshot capabilities lock, docs-drift guard) + command_policy break-glass floor hardening (fail-closed region boundary).
• v0.4.0: OMC/OMX parity — global guidance injection (~/.grok/rules/omg.md); omg update/uninstall/note; self-healing installer + doctor drift checks; kill switches; capabilities lock; verdict-gate hardening + 6 audited security fixes (Fable 5 full-branch GO).
• v0.3.2: QA freeze allowlist UX + pytest marker coalesce; auto PRD from clean UltraQA; autopilot complete short-circuit; autopilot_phase sync on verified.
• v0.3.1: strict-v2 accept lease; residual verdict false-green; integrate/fanout/env isolation hygiene (improve-deep).
• v0.3.0: omg resume + RESUME.md; verdict fence/negation/schema-v2; ultragoal/autopilot/interview/ultraqa skills; omg wiki / hud / lsp.

Details: CHANGELOG.md · docs/research/.

Translation index and maintenance rules: docs/readme/README.md.

MIT · Copyright (c) 2026 ImL1s

See also: CONTRIBUTING.md · SECURITY.md

Inspired by OMC · OMX · OmO — built for Grok. Unofficial; not affiliated.
Core purpose first. No fake parity.