grok-bot-ui

name	Grok Bot UI
description	Use when building a custom UI that talks to Grok Bots (island, inbox, board). Thin wrapper on Grok Bot platform: webhook contract, optimistic send, no key in the browser. Do not use for roster/messaging mechanics alone, and do not use as a copy of pstack Make Bot UI.

Grok Bot UI

Thin wrapper. Read Grok Bot platform first. This file only covers a custom surface that talks to Grok Bots.

This is not pstack /Make Bot UI and not botvillage. Those are one consumer. Reuse the contract. Restyle the product.

What it is

A small app (page, board, island, swipe inbox) the user operates. Each action sends {id, name, prompt} to one host bot. The host either does the work or SendToAgents another bot / channel.

Examples of products that use this contract (do not build them unless asked):

• Live map of bots (island / town / board)
• IG-style inbox: swipe sends a prompt to a bot
• A button that asks one specialist to draft, then another to review

Non-negotiables

1. Run Grok Bot platform for roster, 1:1 vs group, host vs other, untrusted wakes, and human gates.
2. The browser never holds the webhook key. A server you control POSTs to the Grok Bot webhook. Key lives in a chmod-600 file on that server, not in git, chat, or frontend.
3. Ask for the key with SendToUser type secret-request. Never let the user paste it into the chat.
4. Optimistic UI: react locally first, fire the webhook in the background, do not undo the animation if the POST fails (show status).
5. Do not pick a look, layout, or player avatar for the user. Ask. If they shrug, ask one sharper question. Do not draw until they pick.
6. Do not dump transcripts, tool names, or raw snippets on the surface. Show a short goal word + last role at most. Bot speech is generic chatter that fits the look. The player bubble may clip the sent line.
7. Probe the webhook once with {id:"probe",name:"probe",prompt:"",action:"skip"} before live traffic.

Wiring

UI  --POST /api/prompt {id,name,prompt}-->  your server
your server  --POST webhook + Bearer key-->  host bot routine
host bot  --inline work-->  if id is the host
         --SendToAgent-->  if id is another bot or a channel

If the webhook routine does not exist, the host creates it (update_state target routine, trigger { "type": "webhook" }). Then walk the user through that routine’s panel for URL + sender key (see the platform skill). Store {url,key} on the server.

POST shape, headers, timeout, and 200-means-woke: platform skill, “Webhook in”.

Surface rules

• Selecting a bot enables the prompt. Disabled until then.
• Enter sends. Clear the input immediately.
• The prompt chrome must not shift the map/list (position: fixed, preventScroll: true).
• Click a bot for a slim card: pfp, name, title, what they are doing. No events/min, no line counts, no transcript bytes.
• Live roster from agents/<uuid>/profile.json (and optional avatar). Channels from group.json. Tail JSONL only for bots that exist under agents/.
• The user is a player on the surface if the product needs one: not a bot, no house, not in the roster, not click-to-prompt.

Ship checklist

• Platform skill followed (discover roster, no hardcoded ids)
• Webhook routine on the host, key only on the server
• Probe then live
• Host vs other prompt routing
• Look chosen by the user before art
• No secrets in git or the client
• Human gates still on the user (post, merge, pay, speak-as-them)

Credits

UI contract and live-bot-surface idea: Lauren Tan (@poteto).

• pstack, including /Make Bot UI (Cursor plugin 9717366)
• https://x.com/poteto/status/2093023531642863686
• https://x.com/poteto/status/2093023533123400135
• https://x.com/poteto/status/2093023536558555531

Grok Bot mechanics follow Grok Bot’s own agent contract. This file is a distillation, not a fork of botvillage and not a copy of /Make Bot UI. Keep this credit if you ship a surface.