v1.0.5 · PyPI + GitHub

Slow-burn OS for Grok Bot teams.

Queue, Orchestrator, one coding job, many in review. Coordinator is Grok Build on the operator’s machine — not a Grok Bot. Health A is the default lane, not the ceiling. Escalate to swarm-control-plane only when the job is cross-cutting.

GitHub Read the Handbook

Clone

gh repo clone mcp-tool-shop-org/grok-bot-os

Router

python3 route-scratch.py <old> <new>

Not this

# not swarm init — not Role OS

What the OS is

A versioned playbook plus one read-only gh api router. Live QUEUE stays on the Bot VM.

Slow-burn cadence

One Builder coding job at a time, many in review. Orchestrator assigns without waiting for Coordinator. First coding job on a new consumer is an Orchestrator @. Health A is the default lane, not the ceiling.

Four fields, never compressed

Every QUEUE row, Orchestrator @, and scratch ticket carries stop, prerequisite, owner, and fallback in full. “see SLOW-BURN” is forbidden — compression deactivates constraints.

Two machines

Bots on the cloud VM. Coordinator is Grok Build on the operator’s machine. Bot→Robot inbox is HTTP POST /ping on every QUEUE status change. Scratch git pull is fallback if ping ≠ 204. Reviewer squash-merges behavior. Builder never merges.

Escalate, don’t swarm by default

Not testing-os, not swarm-control-plane, not Role OS. Wave a swarm only when the job is cross-cutting (frozen domains, receipts). Role OS stays Codex-side.

Usage

Seed the live queue

cp QUEUE.template.md /workspace/studio/QUEUE.md
# fill stop / prerequisite / owner / fallback
# consumer holds: consumers/<name>.md

Route scratch (no git fetch)

python3 /workspace/studio/route-scratch.py <old_sha> <new_sha>
# exit 0 + empty stdout = silent; exit != 0 → do not advance last-sha

Session-open (Coordinator TUI)

python scripts/coordinator-ping.py last
# if last is ack: gh pr list — silence is not a stall

Finalize emojis (last line)

✅ Bot done, no Coordinator
🔧 Rework — Builder
🛑 hold / secret / policy / merge failed