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

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.3 on PyPI (grok-bot-os) and GitHub Releases. npm @mcptoolshop/grok-bot-os publishes with this tag if Trusted Publisher is registered. Robot→Bot: sendPrompt to Orchestrator's thread. Bot→Robot: HTTP POST /ping on every QUEUE status change (SOCKS on the box). Scratch is fallback if ping ≠ 204.

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, check-queue-fields, and grok-bot-gateway. The Bot VM still clones this repo per CLONE-POLICY.md and runs python3 scripts/route-scratch.py. Coordinator workstation runs python scripts/grok-bot-gateway.py (token file, never argv).

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): coordinator-ping.py last. If last is ack, gh pr list — silence after ack is not a stall. If MagicDNS grok-bot is online, sendPrompt Orchestrator when the standing list is wrong (scripts/grok-bot-gateway.py, docs/COORDINATOR-CHANNEL.md). Scratch to: grok-build only if the ping wire is down. Do not paste Bot-group logs. Do not poll the Orchestrator transcript. TO-COORDINATOR.md is the VM append-only log, not the transport. There is no product slash-command; the host gateway on the Bot VM is the API (Tailscale + SSH as box@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 (Orchestrator squash-merges). Hold / major / behavior go through Reviewer, who squash-merges on pass. Coordinator merges holds / publish / mainnet only and rolls back if main goes south (Panickssery 2024; Kambhampati 2024). Builder never merges.

Orchestrator HTTP-pings Coordinator on every QUEUE status change (ack for coding/review, blocked / coordinator-merge as today). Unstall coding with no PR after 2 hours, not one 15-min clock.

Finalize emojis, last line only: ✅ Bot done, no Coordinator · 🔧 rework · 🛑 Coordinator must act (hold, secret, policy, merge failed).

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; Coordinator workstation Tailscale HTTP to http://grok-bot:1340 using a local token file (never git).

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

Permissions: read this repo; gh api as mcp-tool-shop for scratch routing. Builder never merges. Reviewer squash-merges behavior (--admin if Actions dark). Orchestrator is fallback if the PR is still open, and squash-merges ready patch / Dependabot. Coordinator merges holds / publish / mainnet only. No Dependabot merge of hold PRs. Auto-merge is an optional later consumer-side alternative, not this repo's CI.

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

Layout

License

MIT.

Built by MCP Tool Shop