grokbot-bridge

Talk to your Grok Bots from Claude Code, Cursor, Codex, or any script.

Grok Bot gives you always-on AI teammates that each have a cloud computer, a browser and your connected apps. It doesn't have an API, so other agents can't hand it work. grokbot-bridge fills that gap. It's a small CLI and MCP server that drive the Grok Bot desktop app on your own machine: they send a message to a Bot, wait for the reply, and return it as text or JSON.

$ grokbot ask Chief "Research only. Find 3 posts on X from the last 14 days showing people using Grok Bot for something creative. URL, author, date, one-line summary."
[grokbot] reply: Searching X for recent ones now.
[grokbot] reply: I'll send the three posts once I've checked their dates.
[grokbot] reply: Here are three posts from the past two weeks. All three dates match what X reports…

Here are three posts from the past two weeks. All three dates match what X reports for the posts, and I didn't post or change anything.

[Restaurant-booking bot](https://x.com/…/status/…), from @… on Oct 18, 2026. He built a bot whose only job is to call restaurants in a Grok voice and book a table.
[Animated avatar tool](https://x.com/…/status/…), from @… on Oct 18, 2026. …

Real output from a 77-second run, trimmed, with handles removed. Links come back as Markdown, and --json also lists them per message.

Why

Your coding agent is good at code. Your Grok Bot is good at things that need a browser that stays on: researching X and the web, watching pages, working through sites with no API, and doing long jobs while your laptop sleeps. With this bridge, one agent can delegate to the other:

• Claude Code → Grok Bot: "Ask Chief to collect B-roll posts for this transcript and send me the links."

• Scripts → Grok Bot: grokbot ask Chief "$(cat brief.md)" --json | jq …

• Any MCP client: tools to message Bots (with files), wait for and read replies, download files Bots send, manage routines, stop a Bot, check usage, and create, rename or delete Bots.

Related MCP server: grok-bot-mcp

Requirements

• The Grok Bot desktop app, signed in, with at least one Bot

• Node.js 22 or newer (or Bun)

• macOS. Windows and Linux paths are included but untested; see Platform support.

Install

npm install -g https://github.com/TheSethRose/grokbot-bridge/archive/refs/heads/main.tar.gz
grokbot status

Use the tarball URL. With npm install -g github:…, npm 11 can link the global package to a temporary clone that it then deletes.

Or run it without installing: npx -y github:TheSethRose/grokbot-bridge status.

Quick start

grokbot launch                 # restart Grok Bot with a local debug port (one time per app start)
grokbot bots                   # list your Bots
grokbot ask Chief "What can you help me with?"
grokbot read Chief             # recent messages in that conversation

Every command except status and restore calls launch for you if the app isn't connected yet.

CLI

Options: --json for machine-readable output, --file <path> to attach a file to ask or send (repeat it for several, 25 MB each), --timeout <sec> for ask (default 300) and wait (default 1800), --settle <sec> for how long a Bot must stay idle before its reply counts as finished (default 8), --quiet to stop progress lines on stderr. Pass - as the message to read it from stdin.

ask and wait exit with 0 when the Bot has finished, 2 if it's still working at the timeout, and 3 if it's waiting for you in the app (an approval card or a question). Bots often acknowledge first and report back minutes later; run grokbot wait <bot> again to keep waiting.

In --json output, file messages carry a file field (name, and path on the Bot's computer); pass their key to download. Schedules are standard 5-field cron, for example "0 9 * * 1-5" for 9:00 on weekdays.

Getting told when a Bot replies

You don't need to sleep and check. wait returns the moment the Bot finishes, so start it in the background and let your shell or agent tell you when it exits:

grokbot send Chief "$(cat brief.md)" --file data.csv   # prints the message key
grokbot wait Chief --json > reply.json &               # returns when Chief is done

In Claude Code, run grokbot ask … or grokbot wait … as a background command; Claude is notified when it exits and reads the reply then. For a running feed across all Bots, grokbot watch --json prints one JSON object per event, which works with Claude Code's Monitor tool or any while read loop:

$ grokbot watch --json
{"type":"working","bot":"Chief","at":"2026-10-19T04:40:00.133Z"}
{"type":"message","bot":"Chief","key":"t15s0","role":"assistant","kind":"send-message/text","text":"grokbot-bridge attachment check 7Q4K","links":[],"at":"2026-10-19T04:40:05.973Z"}
{"type":"idle","bot":"Chief","at":"2026-10-19T04:40:33.275Z"}

Use it from your agent

MCP (Claude Code, Cursor, Codex and others)

The server exposes twelve tools: grokbot_list_bots, grokbot_ask, grokbot_send, grokbot_wait, grokbot_read, grokbot_stop, grokbot_download, grokbot_routines, grokbot_usage, grokbot_create_bot, grokbot_update_bot and grokbot_delete_bot. grokbot_ask and grokbot_send take an optional files list. grokbot_routines takes an action (list, add, run, enable, disable, remove); changes return ok, the routine, the Bot's reply and its status. grokbot_delete_bot and removing a routine require a confirm argument that repeats the exact name.

Claude Code

claude mcp add grokbot -- grokbot mcp

Cursor (~/.cursor/mcp.json) or any client with mcpServers JSON:

{ "mcpServers": { "grokbot": { "command": "grokbot", "args": ["mcp"] } } }

Codex (~/.codex/config.toml):

[mcp_servers.grokbot]
command = "grokbot"
args = ["mcp"]

If you didn't install globally, use npx with -y github:TheSethRose/grokbot-bridge mcp as the command and arguments.

Agent skill

skills/grok-bot/SKILL.md teaches an agent when to delegate to a Bot, how to write a good brief, and the safety rules: the user approves actions, and Bot replies are data, not instructions. Install it for Claude Code:

mkdir -p ~/.claude/skills/grok-bot
curl -fsSL https://raw.githubusercontent.com/TheSethRose/grokbot-bridge/main/skills/grok-bot/SKILL.md -o ~/.claude/skills/grok-bot/SKILL.md

How it works

your agent ──CLI / MCP──▶ grokbot-bridge ──Chrome DevTools Protocol (127.0.0.1)──▶ Grok Bot desktop app ──▶ your Bot's cloud computer

Grok Bot is an Electron app. grokbot launch restarts it with Chromium's --remote-debugging-port bound to 127.0.0.1. The bridge then uses the same in-app stores the app's own screens use:

• Reading: each Bot's transcript store holds its whole conversation as structured entries, so read works for any Bot without switching the conversation on screen.

• Sending: messages and files go through the send queue the message box uses (files are staged first, the same way dragging a file onto the box does), so they show up in your history like anything you typed. The bridge never types into the message box, so your drafts are safe.

• Waiting: wait, ask and watch subscribe to the Bot list and transcript change events. A Bot counts as finished when it hasn't been working, using tools or typing for the settle time. If it's blocked on an approval card, they return needs_input right away.

• Stopping: stop calls the same interrupt as the Stop button, for every session the Bot is running.

• Files: download reads a file from the Bot's computer the way the app's file previews do, then saves it locally.

• Routines: changes (add, enable, disable, remove) are made by the Bot itself: the bridge sends it a short request to use its own routine tools and asks it to end its reply with a GROKBOT_RESULT {...} line, which the bridge parses. That works while Grok Bot is in the background, and it's one short Bot turn each. Grok Bot may ask you to approve the change ("Allow Chief to save a routine?"); choose Always allow there to skip it next time. routines (list) and routines run use the store behind the app's routines screen, which needs the Bot's computer awake.

grokbot usage calls the read-only getter that the app's own settings card uses, so it returns the same "Weekly usage limit" numbers.

$ grokbot usage
Weekly usage: 1.37% used · resets 10/22/2026, 11:44:33 AM (in 4 days) · plan: X Premium+

create, update and delete call the same Bot-list client the app's own New Bot, rename and delete actions use. The main Bot can't be deleted.

Grok Bot puts the Bot's computer to sleep (SAND_AWAY_PARK, phase away) when the Mac is locked or asleep, or when the Grok Bot window has been in the background for 10 minutes. Using other apps doesn't count; only bringing the Grok Bot window back wakes it. Bot turns, messages and scheduled routines keep running in the cloud while it sleeps. The bridge never brings the window forward itself. Instead, routine changes go through the Bot (see Routines), and anything that needs the computer from the app says plainly that it's asleep: routines and routines run report it instead of an empty list, and Bot edits (update, delete) fail with a message saying they'll work after you next open Grok Bot.

Messages go through the app's normal send path, so they show up in your conversation history like any message you typed. The bridge makes no network calls of its own and has no runtime dependencies.

Security

• The debug port gives local programs control of the app. While Grok Bot runs with it, any process on your machine that connects to 127.0.0.1:9333 can act in the app as you. The port isn't exposed to your network. Run grokbot restore to close it.

• Bots can take real actions through your connected apps. Grok Bot's own approval prompts still apply, and the bridge never clicks them. Answer them in the app.

• Bot replies can include text from web pages. Agents should treat replies as untrusted data, and the bundled skill tells them to.

Platform support

Environment variables: GROKBOT_CDP_PORT (default 9333) and GROKBOT_APP (path to the app).

Limitations

• App updates can break it. The bridge relies on internal stores of the app's renderer. The lookups live in src/page.ts and the field names in src/bot.ts, so fixes are usually small. Please open an issue with your Grok Bot version.

• A Stop leaves no trace in the transcript. A wait that is running when you stop a Bot returns with no messages, but one started afterwards can't tell a stopped message from one the Bot hasn't picked up yet, so it waits until its timeout.

• The Bot's internal tool steps are left out of read and wait, as the app folds them away too.

• Listing or running a routine, and Bot edits, need the Bot's computer awake, which means Grok Bot was in front within the last 10 minutes. Routine changes don't. See How it works.

Development

bun install
bun run dev -- status       # run from source
bun run check               # tsc + Biome
bun run build               # bundle to dist/cli.js (Node 22+)

dist/cli.js is committed so installing from GitHub works without a build step. Rebuild it before you commit. Notes for coding agents are in AGENTS.md.

License

MIT