Grok Bot Architecture

Grok Bot Architecture is an MIT-licensed reference repository maintained by Tiago Montanha (tiagovilasboas). It documents a pattern in which a desktop assistant works as a crew of specialists on a shared computer, with typed handoffs and human approval on side effects. The repository ships ADRs, crew contracts, example JSON fixtures and Node.js validation scripts rather than a product CLI or hosted service.

What It Is

The project is a pattern and reference, not a hosted OS, a product CLI or a vendor SDK. It helps decide whether a desktop assistant should be a crew (user, chief-of-staff, specialists, connectors, one host computer) or a single chat with every tool. Grok Bot / Cursor is the example host mapping, and the README says the host is replaceable.

How the Validators Work

Running node scripts/validate-all.mjs checks example fixtures for handoffs and interrupts. Broken fixtures must be rejected and fixed fixtures accepted, and CI runs the same command. Rules include:

• default_on_timeout must be wait, never approve.
• from and to must be roles, not "the agent" or "the model".
• refs must be pointers such as paths, SHAs, issue ids or URLs, not transcript blobs.
• Decisions and decided_by belong on the interrupt record and are filled only by a human.

Architecture and Decisions

Six ADRs cover a crew of specialists rather than a monolith, shared computer versus desktop chat, human-in-the-loop on merge, deploy, secrets and messaging-as-user, connectors over the browser, token thrift as a control, and cloud agents for isolated code work. The example crew includes a chief-of-staff that plans, routes and interrupts, plus specialists such as Inbox, Eng, Vitrine, Cibersec and Carreira, each with a defined write boundary. Connectors are schema'd MCP or API integrations with allowlists.

When Not to Use It

The README advises against a crew when one human, one repo and one chat is enough, since a second specialist without a secrets, write-boundary or context-window collision adds ceremony.