AI teammates that finish the work — on your machine.
Message Bots like teammates. Give one a job, keep it around, add another when the work grows. They remember how you work, hand off to each other, and come back when something needs your approval.
OpenGrokBot is the open-source Grok Bot alternative. Same product shape. Same primitives. Your computer instead of theirs.
Unofficial community project for learning. Not affiliated with xAI, Grok, or Cursor. See Disclaimer.
You bring your own model. OpenGrokBot does not ship one. Point it at local Ollama (/v1) or any OpenAI-compatible API (DeepSeek, OpenRouter, MiniMax-style endpoints, and the rest).
- Install Node 20+ and pnpm.
- Clone, install, start:
git clone https://github.com/nickylin/OpenGrokBot.git
cd OpenGrokBot
pnpm install
pnpm start- Open http://127.0.0.1:3088.
- Settings → Harness: pick the engine (OpenAI-compatible API, Ollama, Codex CLI, Cursor Agent, or DeepSeek Harness). If a local CLI is missing, copy the install command and install it yourself. For HTTP engines, Settings → Models: paste Base URL, API key, and model. Ollama: Base URL like
http://127.0.0.1:11434/v1. If that server does not check keys, a dummy key is fine. - Test connection.
- Pick a Bot in the left roster and send a message.
Keys stay on this machine in ~/.opengrokbot/settings.json. Do not commit them. Do not put them in a Bot description or chat.
Defaults bind to 127.0.0.1:3088. Override with OPENGROKBOT_HOST, OPENGROKBOT_PORT, or OPENGROKBOT_HOME. pnpm dev watches files. pnpm typecheck runs tsc --noEmit.
OpenGrokBot ships an unsigned Electron .dmg for local use. The desktop app starts the Fastify server for you and opens the UI in a window.
Prerequisites: macOS, Node 20+ on PATH (the packaged app spawns your system node), pnpm.
Build a DMG:
pnpm install
pnpm build:dmgArtifacts land in release/ (for example release/OpenGrokBot-0.2.0.dmg, release/OpenGrokBot-0.2.0-mac.zip, and release/mac/OpenGrokBot.app).
If electron-builder hangs on the DMG step, the app bundle and zip are still valid. Create a DMG manually:
hdiutil create -volname "OpenGrokBot" -srcfolder release/mac/OpenGrokBot.app -ov -format UDZO release/OpenGrokBot-0.2.0.dmgInstall an unsigned build: macOS may block the first launch. Right-click OpenGrokBot → Open, or run:
xattr -cr /Applications/OpenGrokBot.appDev with Electron:
pnpm dev:desktopThis runs the TypeScript dev server and opens Electron once /api/health responds.
Limitations (v0.2): requires Node 20+ on PATH (the app spawns your system node to run the server). No code signing, auto-update, or menu-bar tray. CLI harnesses (codex, cursor, dsh) still need separate install on the machine. User data stays in ~/.opengrokbot/ either way.
When the tab or Electron window is in the background, OpenGrokBot can alert you when:
- a Bot finishes a reply
- a Bot needs approval (
Blocked) - a scheduled routine starts (via roster polling)
Turn this on in Settings → Agent → Background notifications. The browser or macOS will ask for permission the first time. Click a notification to focus the app and open that Bot. Notifications are skipped while you are actively viewing the app in the foreground.
Official Grok Bot (docs): named teammates with jobs and compounding context. Each one works a persistent computer — browser, filesystem, terminal — and messages you like iMessage, not like a chatbot dump.
| Grok Bot | OpenGrokBot | |
|---|---|---|
| What you talk to | Named Bots with jobs | Same |
| Sidebar | Bot roster, not chat history | Same |
| Computer | Cursor cloud VM, keeps running when the laptop sleeps | Your machine. Sleep stops work. That’s the trade. |
| Workspace | One /workspace for every Bot |
One folder on disk, same sharing model |
| Model | Cursor / Grok picks | You bring any OpenAI-compatible API |
| Setup | A message, not a workflow builder | Same |
| Price | Cursor / SuperGrok plan | Free. MIT |
This is a working local app, not a README stub.
In this release
- macOS desktop app — unsigned Electron
.dmg; spawns the local server and opens the UI in a window - Named roster plus Create a Bot (color, shape, expression)
- Harness switcher — OpenAI-compatible HTTP, Ollama, Codex CLI, Cursor Agent, or DeepSeek Harness, with install hints for missing local CLIs
- Avatars — 8 shapes and 8 expressions; lifecycle motion (idle / thinking / working / waiting / blocked / done) on the face, not a separate spinner
- Token streaming — OpenAI-compatible harness streams reply text into the bubble as tokens arrive (CLI harnesses still return full replies)
- 1:1 and group threads; group messages route through a coordinator Bot and mirror member replies into the thread
@mentions (clickable in chat) andmessage_bothandoffs shown as system strips, not user bubbles- Markdown in bubbles — tables, horizontal rules, headings, lists, bold, inline code, fenced blocks, links
- Per-Bot markdown memory and a shared workspace on disk
- Shell commands behind Allow once / Always allow / Deny; Allow resumes the agent loop with command output
/routinepicker — type/in the composer to fire a Bot's routine prompt- Scheduled routines — in-process scheduler fires enabled routines while the app is open (Settings → Agent → Host scheduler)
- Background notifications — browser or macOS alerts when a reply finishes, approval is needed, or a routine starts
- Settings → Agent: clear roster or reset to the starter bots in
data/bots/ - Computer pane as a status preview (purple icon while active, time-of-day wallpaper), not a live VM
Not yet
- Real browser / computer-use
- launchd / login-item scheduler when the app is closed
- MCP connectors
- Auto-review model
- Work while the laptop sleeps
The rest of the official list below is the north star, not a claim that every item is wired today.
The roster is the product, presence lives on the avatar, and the interface should ask less of you over time.
Settings → Harness picks the engine for every Bot turn:
| Engine | What it uses |
|---|---|
| OpenAI-compatible | Your Base URL + API key + model (DeepSeek, OpenRouter, vLLM, etc.) |
| Ollama | Local /v1 endpoint |
| Codex CLI | codex on this machine |
| Cursor Agent | cursor CLI / agent on this machine |
| DeepSeek Harness | dsh on this machine |
If a CLI harness is selected but not installed, Settings shows a copy-paste install command. HTTP engines still configure models under Settings → Models.
Create Bot → pick Color, Shape, and Expression.
Shapes: circle, oval, squircle, pill, triangle, hexagon, cloud, teardrop — flat silhouettes with diagonal-line eyes in the shape picker, closer to the official set.
Expressions: smile, calm, grin, sleepy, wink, wide, glasses, dots.
Lifecycle motion (roster + typing row): idle is calm; thinking/working/waiting/blocked change eye style and motion; done settles then returns to idle. Hover a roster row to see the Bot’s current action without extra chrome.
- Bot replies render Markdown — including
---rules and| tables |. - Group chats (2–6 Bots): your message goes to a router Bot (e.g. Chief); member replies appear in the same thread with name + avatar.
- Handoffs (
[Handoff from …]) render as a centered system strip, not a user bubble. - Click an
@Botchip in a thread to jump to that Bot’s chat.
- + menu: New Bot, New conversation, New group.
- Settings → Agent → Roster: clear all bots (and transcripts) or reset to the seed YAML in
data/bots/.
Message Bots like teammates. Create a Bot, describe the job in a sentence, start talking. Chief of Staff, Sales Outbound, Inbox, Account Manager, Talent Scout — focused Bots beat a General Helper.
Work with many Bots at once. They run in parallel. Put 2–6 in a group thread and they pass work with message_bot. You are not the router.
Come back when approval is needed. Outbound, publish, pay, shell: Allow once / Always allow / Deny. A yes covers that action, not the past.
Context compounds. Each Bot keeps its own memory, thread, and routines. Files, cookies, and logins sit on the shared computer so handoffs don’t mean re-login.
Show a Bot how it’s done. Walk it through once, save a Skill, pin a Routine on that Bot. The schedule belongs to the teammate, not to a random cron tab.
The computer has three levels. Purple status by default. Pin a preview of its screen. Take over only for password / 2FA / CAPTCHA, then hand it back. You never type secrets into chat.
Connectors first, computer-use when you must. MCP and APIs where they exist; the local browser profile when they don’t. All Bots share that profile — one user, one browser — matching official isolation (between users, not between Bots).
Same prompt the official docs start with:
Pull this week’s pipeline review list. Skip anyone already in an active sequence. Research the top five accounts, draft outreach in my voice, and leave me drafts to approve by tomorrow morning.
Tell it what to do, where to work, what finished looks like. Correct it. Turn the stable path into a routine and pin it on that Bot.
Official Bots keep working when your laptop is closed. That needs their cloud computer.
OpenGrokBot runs on the host OS. Close the lid, the team stops. In exchange: no $120–300/month seat, no logins sitting in someone else’s VM, no waiting on a Bot API that does not exist.
If you need 24/7, keep a small machine awake — or stay on official Grok Bot.
| Path | What |
|---|---|
~/.opengrokbot/settings.json |
API key, models, paths |
~/.opengrokbot/bots/ |
Roster YAML (seeded from data/bots/ on first run) |
~/.opengrokbot/transcripts/ |
Chat history |
~/.opengrokbot/memory/ |
Per-Bot MEMORY.md |
~/.opengrokbot/workspace/ |
Shared files the Bots can read and write |
License: MIT.
OpenGrokBot is an independent, unofficial open-source learning project. It is not a product of xAI, Grok, or Cursor, and it is not endorsed, sponsored, or certified by them.
Grok, Grok Bot, xAI, and Cursor are trademarks or product names of their respective owners. We use those names only to describe what this project studies and how it differs. We do not claim any right in those marks, and we are not the same company.
This repository does not provide access to official Grok Bot, Cursor accounts, or xAI cloud computers. Anything you run here is on your own hardware, with keys you bring, at your own risk.