Metadata-Version: 2.5
Name: grok-bot-os
Version: 1.0.3
Summary: Operating system for Grok Bot teams: slow-burn Health A queue. Not the testing-os dogfood-swarm CLI.
Project-URL: Homepage, https://mcp-tool-shop-org.github.io/grok-bot-os/
Project-URL: Repository, https://github.com/mcp-tool-shop-org/grok-bot-os
Author: mcp-tool-shop
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Description-Content-Type: text/markdown

<p align="center">
  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/grok-bot-os/readme.png" width="280" alt="grok-bot-os">
</p>

<p align="center">
  <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
</p>

# grok-bot-os

<p align="center">
  <a href="https://github.com/mcp-tool-shop-org/grok-bot-os/actions"><img src="https://github.com/mcp-tool-shop-org/grok-bot-os/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://www.npmjs.com/package/@mcptoolshop/grok-bot-os"><img src="https://img.shields.io/npm/v/@mcptoolshop/grok-bot-os.svg" alt="npm"></a>
  <a href="https://pypi.org/project/grok-bot-os/"><img src="https://img.shields.io/pypi/v/grok-bot-os.svg" alt="PyPI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
  <a href="https://mcp-tool-shop-org.github.io/grok-bot-os/"><img src="https://img.shields.io/badge/landing-page-0ea5e9.svg" alt="Landing page"></a>
</p>

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`](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
   `SendToAgent`s Bot `DELIVER`s 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

| Path | What |
|------|------|
| `SLOW-BURN.md` | Generic OS: seats, QUEUE class, pipeline, emojis |
| `ROUTE.md` | Scratch `to:` ids + poll + Orchestrator outbox (fallback mailbox) |
| `CLONE-POLICY.md` | What the VM may clone; Coordinator `git pull` of `the local scratch-transport clone` |
| `QUEUE.template.md` | Columns including class + four constraint fields |
| `TO-COORDINATOR.template.md` | VM append-only log format (not the transport) |
| `bots/*.md` | Paste-ready profiles. `coordinator.md` is not a Bot |
| `scripts/route-scratch.py` | `gh api` compare → DELIVER lines |
| `scripts/grok-bot-gateway.py` | Coordinator Tailscale client (`listAgents` / `sendPrompt` / tail) |
| `consumers/` | Per-repo catalog, holds, hours |
| `docs/RESEARCH.md` | Study-swarm citations + implications |
| `docs/COORDINATOR-CHANNEL.md` | Tailscale + SSH + host gateway (preferred inbound) |
| `site/` | Landing + Starlight handbook |

## License

MIT.

---

Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
