# Grok Bot Architecture

> A reference pattern of ADRs, crew contracts and validators for building multi-agent desktop assistants with fail-closed human-in-the-loop gates.

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.

## Features
- Architecture decision records (ADR 0001–0006)
- Crew role, handoff and HITL contracts
- Node.js validators for handoff and interrupt JSON fixtures
- Broken and fixed example fixtures checked in CI
- Fail-closed human approval on merge, deploy, secrets and messaging-as-user
- Connectors-over-browser guidance
- Token thrift and context engineering guidance
- Cookbook for when to use the pattern and failure modes

## Integrations
MCP, Cursor, Grok Bot

## Platforms
API, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/tiagovilasboas/grok-bot-architecture
- Documentation: https://github.com/tiagovilasboas/grok-bot-architecture/blob/main/docs/architecture.md
- Repository: https://github.com/tiagovilasboas/grok-bot-architecture
- EveryDev.ai: https://www.everydev.ai/tools/grok-bot-architecture