# Rea teardown: nickvasilescu/bot-hq (2026-11-17, standard 45-min box, mode: free single-agent) *Test run 1 of Rea's SOP. Run by hand, following `rea-instructions.md` v1.0 step by step. Gaps found while running are noted in brackets and were fixed in v1.1.* ## 1. Bottom line - bot-hq is Nick's open-source "Grok Bot you own": a chat app over **Hermes agents**, with one **Orgo** screen per bot, **Composio** apps behind approval cards, and **xAI** voice and X search. It's MIT and about 11k lines of TypeScript, built in about 3 hours by one prompt in T3 Code. - Its real value for Epic isn't the app. It's **four patterns we can copy into our Grok Bot team today, for free**: approvals inside the tool call, a 3-hop cap on bot-to-bot messages, subagents that report back and never message the user, and a cache-stable system prompt. - Running it ourselves is the natural "Hermes/Orgo later" step. It needs a paid Orgo computer plus xAI and Composio keys, and caps at 4 bots per computer. **Don't stand it up without Trevor's yes on cost.** ## 2. Target and version - Repo: https://github.com/nickvasilescu/bot-hq, commit `decf9a2`, pushed 2026-11-11 03:24 (America/New_York). 4 commits, 318 stars, 126 forks when checked on 2026-11-17. Licence: MIT; bot artwork and some icons are excluded (Grok Bot's). - Why Trevor cares: he's building a Planner/Builder/Reviewer team in Grok Bot with Hermes on Orgo to follow. bot-hq is Nick's working answer to "Grok Bot-style team, on Hermes, on Orgo, with Composio", the exact stack in Trevor's plan. - *[Gap 1: v1.0 had no "pin the version" step. Added the commit hash here by hand, then fixed the SOP.]* ## 3. Already-exists list (Step 1: source pass) | Piece | Link | Licence | Notes | |---|---|---|---| | bot-hq itself | github.com/nickvasilescu/bot-hq | MIT | The target | | grokbot-clone (upstream) | github.com/nickvasilescu/grokbot-clone | not checked | README: "Continued from grokbot-clone". Earlier, Grok-API-only version (248 stars, created 2026-11-09) | | OrgoAI/bops (design inspiration) | github.com/OrgoAI/bops | FSL-1.1-ALv2 | README: "screen look is an original implementation inspired by OrgoAI/bops; no code or assets from that repository are used" | | Hermes Agent (engine) | github.com/NousResearch/hermes-agent | open source | Runs every bot's loop, memory and model | | Orgo (computers) | orgo.ai / docs.orgo.ai | paid service | One Linux computer, up to 4 screens | | Composio (apps) | composio.dev | paid service, has a free tier | Already connected in Trevor's Grok Bot | | nicks-stack (Hermes template for Orgo) | github.com/nickvasilescu/nicks-stack | not checked | "ready-to-run Hermes AI agent template for Orgo... zero secrets baked in" | | orgo-template-hermes-desktop | github.com/nickvasilescu/orgo-template-hermes-desktop | not checked | Boots a Hermes VM with computer use baked in | *[Gap 2: v1.0's source pass only searched outward for clones. The two most useful finds (grokbot-clone, bops) came from reading the target's own README "continued from / inspired by" lines. The SOP now traces upstreams.]* ## 4. Feature map (Step 2) | # | Unit | Question | Evidence needed | Status | |---|---|---|---|---| | U1 | Architecture | What talks to what? | ARCHITECTURE.md, README diagram | Answered | | U2 | Bot engine | How is each bot run, and with which model? | `server/src/engine.ts`, README | Answered | | U3 | Bot-to-bot comms | How do bots hand off, and what stops loops? | `agent/tools.ts` send_to_bot, `agent/loop.ts` | Answered | | U4 | Subagents | How does a bot delegate to a child? | `agent/subagents.ts` | Answered | | U5 | Approvals / safety | What needs a human OK? | `mcp.ts`, `agent/loop.ts`, README limits | Answered | | U6 | System prompt | What does the app tell each agent? | `agent/prompt.ts` | Answered | | U7 | Screens / computer | How do bots get their own computer? | ARCHITECTURE.md, orgo-builder-guide.md | Answered | | U8 | Install, keys, cost | What does it take to run? | README install, `.env.example`, Orgo guide | Partial (Orgo prices not in repo) | | U9 | How it was made | Which method produced it? | Video description (ceU0tS6sXbU), README credits | Partial (prompt text shown on screen only) | ## 5. Teardown (tagged) **U1 Architecture** - OBSERVED: browser ⇄ Node server (Hono + SQLite) over HTTP + SSE and a WebSocket for VNC. The server calls each bot's Hermes gateway via `POST /v1/responses`; Hermes calls back into the server's MCP endpoint `/mcp/` for app tools. (`docs/ARCHITECTURE.md` L5-11; README mermaid diagram) - OBSERVED: server deps are hono, better-sqlite3, croner, openai, @composio/core, ws, zod. Web is React + zustand + noVNC. (`server/package.json`, `web/package.json`) - OBSERVED: about 11,000 lines of TS/TSX across `server/src` and `web/src` (wc). **U2 Bot engine** - OBSERVED: the first ("primary") bot is the Hermes agent already on the computer. The app "never restarts it, stops it, or writes its config.yaml". Each extra bot gets its own Hermes home and gateway, with ports from 8650. (ARCHITECTURE.md, "The primary engine"; Components table) - OBSERVED: model is picked per bot, or by signing in to a subscription (e.g. Claude Pro/Max) on the bot's own screen. README warns: "Check your provider's terms before running an agent on a consumer subscription." - INFERRED: this is how Nick gets "different brains per bot", which matches Trevor's Grok / ChatGPT / Claude / Gemini goal. **U3 Bot-to-bot comms** - OBSERVED: `send_to_bot(bot_name, message)` queues a message to the other bot; "Their reply will arrive later as a new message to you." Refuses rooms and self-sends. **Hop cap:** `if (ctx.depth >= 3) return 'Too many hops between bots; answer the user directly instead.'` (`server/src/agent/tools.ts` L257-270) - OBSERVED: group chats via `create_group` / `post_to_group`, and `stay_silent` to end agent-to-agent turns quietly. (`tools.ts` L168, L273, L292; `prompt.ts`) - INFERRED: this mirrors Grok Bot's own SendToAgent / group-chat model (the README says the interface is "modeled on Grok Bot"). **U4 Subagents** - OBSERVED: a subagent is a hidden child bot with its own context and screen, max 4 per parent. Its instructions say: "When you finish (or get blocked), call send_to_bot with bot_name '' and a concise result, then stop. Do not message the user directly." The code comment names Grok Bot's CheckSubagent / MessageSubagent / StopSubagent as the model. (`server/src/agent/subagents.ts` L5-30) **U5 Approvals / safety** - OBSERVED: approvals happen *inside the MCP call*. Read-only Composio tools run at once; anything else posts a card with Allow / Always allow / Don't allow. A denial "tells the agent not to retry", and a new user message or a timeout closes the card as "skipped". (ARCHITECTURE.md "Approvals"; `agent/loop.ts` L210-218) - OBSERVED (stated limit): "What a bot does through its browser or shell is not gated." Experimental, no security audit, and bots on one computer can read each other's files. (README "Status and limits") **U6 System prompt** - OBSERVED: the app adds a short "Team app" block every turn: who you are, the app's tools, your computer, style ("Write like a sharp colleague texting... Never say something is done unless a tool result shows it"), and context (connected apps, team, routines, skills). It must "stay byte-identical between turns... because it sits in the cached part of the prompt: nothing here may depend on the clock." (`server/src/agent/prompt.ts` L7-61) **U7 Screens / computer** - OBSERVED: one Orgo Linux computer. The primary bot uses the default screen; each other bot leases its own Orgo screen, max 4 per computer, so 4 bots. Each screen gets its own Chrome profile and DevTools port. VNC is relayed by the server, so the computer password never reaches the browser, and "watch" mode drops input. (ARCHITECTURE.md Components; README) - OBSERVED: `docs/orgo-builder-guide.md` is a 79 KB evidence-cited study of Orgo's docs, with `[inferred]` markers and line citations. Its notes include: custom templates need Orgo's Scale plan to publish (launching works on any paid plan), no inbound networking to the VM, and a 999-computer ceiling per account. - INFERRED: that guide is itself a free example of the REA-style evidence discipline Rea uses: claims, citations and inferred markers. **U8 Install, keys, cost** - OBSERVED: needs Node 22+, a Hermes gateway with API server on, and keys `ORGO_API_KEY`, `ORGO_COMPUTER_ID`, `COMPOSIO_API_KEY`, `XAI_API_KEY`, `SESSION_SECRET`. Installs to `/opt/hq` under supervisor via `install-on-computer.sh`; public URL on port 8787 via Orgo; Google sign-in through Composio. (README "Install on the computer"; `.env.example`, placeholders only, no secrets) - UNKNOWN: Orgo plan prices, xAI usage cost and Composio tier for this load. Not in the repo; not looked up (pricing pages weren't in scope for a free pilot). - OBSERVED: `tests/e2e.mjs` "calls real providers", so it isn't a free test. **U9 How it was made** - OBSERVED (video description, ceU0tS6sXbU): Nick toured Grok Bot, Muse, Dots, Hermes, Instinct and Duet, took "the best part of each", "sourced every piece before prompting: an open source repo, an API or an MCP for each feature", then sent one dictated prompt to Fable 5.2 in T3 Code; "3 hours later" it was hosted on an Orgo computer. - GATED/NOT PUBLISHED: the prompt text itself (shown on screen, not in the repo or description). ## 6. How it works end to end, plus the secret sauce A user chats in a Grok Bot-style web app → the Node server queues the turn for that bot → it posts to the bot's own Hermes gateway → Hermes thinks with whatever model or subscription that bot uses → when it needs an app, a file, another bot or a schedule, it calls the server's MCP tools → write actions pause for an approval card → results stream back as transcript rows, while the bot's Orgo screen is watchable live. **Secret sauce (3 decisions):** 1. **Don't build an agent loop. Wrap Hermes.** The app only adds UI, screens, apps and approvals, so every bot can use any model. 2. **Put approvals in the tool layer (MCP)**, not in each agent, so they work the same for every engine. 3. **Reuse proven shapes**: Grok Bot's UX and subagent/handoff model, bops' screen look (original code), and grokbot-clone's earlier work. That's Nick's "already 90% there" in action. ## 7. Rebuild plan for Epic **Reuse vs build** | Need | Reuse | Build (Epic) | |---|---|---| | Team handoffs | Grok Bot SendToAgent (already live) | Add bot-hq's rules: **max 3 hops** then answer the requester; **subagents report to their parent only** | | Approvals | Grok Bot's built-in approval cards | Nothing new now. Later on Hermes, bot-hq's MCP-approval pattern | | Agent prompts | bot-hq `prompt.ts` structure | Keep Planner/Builder/Reviewer descriptions stable (no dates in them) and add the "never say done without a tool result" line | | Multi-brain bots | Hermes per-bot model (bot-hq U2) | Later: one Orgo computer running bot-hq with 4 bots (e.g. Grok, Claude, GPT, Gemini brains) | | Evidence discipline | REA tags; bot-hq's Orgo guide style | Rea uses OBSERVED/INFERRED/UNKNOWN/GATED on every claim | **Stack map** - **Grok Bot now (free, this week):** the four patterns above go into Planner/Builder/Reviewer descriptions, and Rea is created as a Grok Bot agent. - **Hermes/Orgo later (paid, needs yes):** bot-hq on one Orgo computer = a 4-bot Hermes team with a Grok Bot-like UI, reachable at an `orgo.dev` URL. Keys go in the box's secret store, never in a template image. - **Composio:** already the hub; bot-hq uses the same Composio, so connected apps carry over conceptually (bot-hq needs its own Composio API key). - **Sites:** any review/demo pages on Cloudflare Pages (fleet law), not Orgo URLs, for anything Trevor shares. **Costs:** patterns = free. bot-hq self-host = Orgo paid computer (price UNKNOWN; check before asking), xAI API usage, Composio key, model subscriptions/keys. Nick's comparable swarm run (Higgsfield) cost about $122; a single bot-hq install should be far less, but that's unverified. **Licence / IP:** MIT lets us fork and use it. Do **not** reuse the Grok Bot artwork or icons it bundles (excluded from MIT). Rename "Grokbot" strings before anything client-facing. bops is FSL, so don't use its code in anything offered as a hosted product; bot-hq says it uses none. *[Gap 4: v1.0 had no licence/IP row. Added it here, then fixed the SOP.]* **First 3 build steps** 1. **Builder (free, today):** add to Planner/Builder/Reviewer descriptions: "Max 3 agent-to-agent hops on one job, then report to the requester"; "If you were delegated a job, report only to the agent that sent it"; "Never say done without a tool result." 2. **Builder (free):** create **Rea** as a Grok Bot agent from `rea-instructions.md` §A, then run it on one marketing target (e.g. a competitor's book funnel). 3. **Planner (free to write, paid to run):** a one-page "bot-hq on Orgo" pilot card with real prices pulled from Orgo/xAI/Composio pricing pages, for Trevor's yes/no. ## 8. Free vs gated ledger - Free: the whole repo, architecture, prompts, install steps, Orgo guide, the related video description. - Paid to *run*: Orgo computer, xAI key, Composio key, model access. - Not published: the exact one-shot build prompt (on screen only). - Not checked: Orgo, xAI and Composio prices. - *[Gap 6: found no secrets in the repo (`.env.example` = placeholders), but v1.0 had no rule for what to do if we had. Added one.]* ## 9. Checklist closeout U1–U7 answered. U8 partial (prices unknown). U9 partial (prompt not published). Nothing unresolved that blocks step 1 or 2. *[Gap 3: v1.0 didn't say which tool to use for a source repo. REA's own skill says not to use REA there. Normal repo reading was right, and the route table now says so.]* *[Gap 5: about 120 source files didn't fit a 45-min box at full depth. "Smallest overview first, go deep only on open questions" made it fit and is now explicit.]* ## 10. One next step Builder adds the three rules in step 1 to Planner/Builder/Reviewer (free, about 10 minutes).