English | 日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

grok-bot-os

Versioned operating system for Grok Bot teams. Orchestrator, Builder, Reviewer, and Researcher sit in a Grok Bot group chat. Coordinator is Grok Build on the operator's machine — not a Grok Bot. Work moves through a live QUEUE.md on the Bot VM. Default cadence: one coding job at a time, many in review, Coordinator merges when the human is back. Health A is the default lane, not the ceiling — Coordinator can open Health B–D and named features on this same queue.

Status: v1.0.0 on PyPI (grok-bot-os), npm (@mcptoolshop/grok-bot-os), and GitHub Releases.

What this is not

• Not the testing-os dogfood-swarm CLI (swarm init / 10-phase).
• Not swarm-control-plane (SQLite waves, domain freeze, receipts).
• Not Role OS. Role OS orchestrates Codex. This OS orchestrates Grok Bots on the cloud VM via QUEUE.

Stay on this queue for one-locus work (Health A default; later classes when Coordinator names them). Escalate to swarm-control-plane only when the job is cross-cutting (frozen domains, wave receipts — Kim 2025 is about seats, not a Health A ceiling). Grounding: docs/RESEARCH.md.

Install / use

Registries (optional — the live OS is still a git clone on the Bot VM):

pip install grok-bot-os
npm install @mcptoolshop/grok-bot-os

pip installs route-scratch and check-queue-fields. The Bot VM still clones this repo per CLONE-POLICY.md and runs python3 scripts/route-scratch.py.

1. Clone the OS and the consumer per CLONE-POLICY.md. Coordinator workstation: a local clone of this repo. Bot VM: /workspace/studio/<repo> only after a ticket names owner/repo. Never copy the Coordinator tree onto the VM. Never copy .swarm. Bots never copy the scratch transport clone.
2. The generic OS contract is SLOW-BURN.md in this git. Consumer holds (PR numbers, hours) live in consumers/<name>.md. Do not overwrite a VM SLOW-BURN.md that still carries consumer PR numbers until Orchestrator is reading both git files.
3. Paste all four Bot profiles (Name / Title / Description) from bots/orchestrator.md, bots/builder.md, bots/reviewer.md, and bots/researcher.md before adding anyone to the group. Then add those four to one Grok Bot group chat — still four seats, no fifth (Kim 2025). Coordinator is not a Bot (bots/coordinator.md).
4. Seed live QUEUE.md on the VM from QUEUE.template.md plus the consumer file (stop / prerequisite / owner / fallback in full). Live QUEUE and TO-COORDINATOR.md stay on the VM.
5. Run Orchestrator once (clock or @Orchestrator) so it pulls consumer main and assigns the first ready row. The first coding job is an Orchestrator @, never a human paste and never “add Orchestrator after idle.”
6. Only then may Builder code. Scratch routing: ROUTE.md + scripts/route-scratch.py on the VM. Poll with gh api only (no git fetch). Fail-closed: seed last-sha first; do not advance it on exit != 0. Empty stdout after exit 0 = silent. Researcher SendToAgents Bot DELIVERs only.

Coordinator session-open (Grok Build TUI on the operator's machine): git pull the local scratch-transport clone, then read new to: grok-build envelopes. Do not paste Bot-group logs. TO-COORDINATOR.md is the VM append-only log, not the transport. The TUI has no inbound ping and no API to Grok Bot. Do not reconstruct state from the group transcript (KC 2026).

QUEUE contract (do not compress)

Every QUEUE row, Orchestrator @, and scratch ticket carries stop / prerequisite / owner / fallback in full. see SLOW-BURN is forbidden (Sun 2026). Ready Dependabot / patch rows skip Reviewer. Hold / major / behavior still require Reviewer 🛑. Coordinator still merges every coordinator-merge.

Builder does not review itself. Reviewer pass on a mergeable PR is 🛑. Merge stays on Grok Build (Panickssery 2024; Kambhampati 2024).

Finalize emojis, last line only: ✅ Bot done, no Coordinator · 🔧 rework · 🛑 Coordinator must act.

Trust model

Touches: public git playbooks; gh api against mcp-tool-shop/rig-bridge-scratch from an already-authenticated gh on the VM; markdown QUEUE on the VM.

Does not touch: npm registry, consumer main, Coordinator swarm sqlite (.swarm, ~\.grok\*.sqlite), PATs, auth.json, mcp_credentials.json, telemetry, GitHub MCP token fields.

Permissions: read this repo; gh api as mcp-tool-shop for scratch routing. Bots never merge. Coordinator merges every coordinator-merge (--admin if Actions dark). Reviewer 🛑 is required for hold / major / behavior. Ready patch / Dependabot PRs skip Reviewer. Auto-merge is an optional later consumer-side alternative, not this repo's CI. No Dependabot merge of hold PRs.

No telemetry. No secrets in source or in tool-call examples.

Layout

License

MIT.

Built by MCP Tool Shop