Metadata-Version: 2.5
Name: grok-bot-os
Version: 1.0.1
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">
  <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.1 on PyPI (`grok-bot-os`) and GitHub Releases. npm `@mcptoolshop/grok-bot-os` publishes with this tag if Trusted Publisher is registered. Coordinator pings Orchestrator over Tailscale (`sendPrompt` to Orchestrator's thread at `http://grok-bot:1340`); scratch `to: grok-build` is fallback.

## 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):
if MagicDNS `grok-bot` is online, `sendPrompt` / `tail` Orchestrator's
thread (`scripts/grok-bot-gateway.py`, `docs/COORDINATOR-CHANNEL.md`)
**and** `git pull` the local scratch-transport clone. If the wire is
down, scratch `to: grok-build` only. Do not paste Bot-group logs.
`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.
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; 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. 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

| 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>
