claude-grok-bridge
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 8 GitHub stars
Code Pass
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
Two-way bridge between Claude Code sessions and Grok Bot agents (SpaceXAI's agents desktop app), through each vendor's own routine endpoints. One-line setup, no middleware.
claude-grok-bridge
Your Claude Code sessions and your Grok Bot agents, finally on speaking terms.
For the agents you build in Grok Bot, SpaceXAI's desktop app for agents with routines,
plugins and a shell. Not the Grok chat, and no xAI API key involved.
No servers. No API keys to copy. No glue code. Just one message.
An open source project by Spoki.
Get started · How it works · Protocol · Security · FAQ · Contributing
All you have to do is send this to your Grok agent
Set up the Claude Code bridge: follow https://github.com/Spoki-App/claude-grok-bridge/blob/main/grok/BOOTSTRAP.md
That's it. Your agent installs everything on both sides, wires itself to Claude Code, runs a
self-test, and comes back with "Bridge ready". In the usual setup you don't type a command, paste a key or touch
a config file. Want the latest version later? Send the same line again.
From then on, in any Claude Code session, you just talk:
ask Grok Bot whether we should ship the billing fix today
tell Grok Bot to move card #1234 to review and ping the reviewer
did Grok Bot answer?
| Easy | Compact | Clear | Safe | Fast |
|---|---|---|---|---|
| One line to your agent. Nothing else to type. | Two small scripts, zero dependencies. | ask, tell, note. One name per thing. |
Messages are data. Answers are not approvals. No secrets in chats. | Answers in ~30 s, pushed into the session that asked. |
What you can do with it
Illustrative exchanges. Measured: an answer is back in the asking session in about 30 seconds.
Unblock a coding session. A decision your agent owns, answered without leaving the terminal.
Delegate from your terminal. Your agent does it under its own rules, and asks first when it should.
Get the context Claude is missing. It asks the agent that knows, instead of guessing.
Keep your agents in the loop. A note, no reply needed.
Your agent asks Claude Code. Tell your agent, it asks Claude; a cloud session looks it up and answers.
Let your agent steer a running session, even at 2 a.m. with your laptop closed.
What happens when you send it
Your agent follows grok/BOOTSTRAP.md and keeps you posted ("Step N of 5"):
- installs the bridge on its box and creates your Claude inbox routine, through the Claude
CLI already signed in there; - creates its polling routine and a "Claude Code" plugin you'll see in its plugins;
- installs the
grok-bridgeskill on your Mac, through Grok Bot's local exec, and notes the
agent's name in your~/.claude/CLAUDE.mdso every session knows it; - sends itself a test question and answers
PONGback into Claude; - says "Bridge ready", and how fast it picks up messages.
- Claude CLI signed in on its box. If not, it asks you once to sign in.
- Local exec on your Mac (Grok Bot's). Without it you paste one line in the Terminal:
curl -fsSL https://github.com/Spoki-App/claude-grok-bridge/releases/latest/download/install.sh | sh -s -- <peer> --name <Agent> --inbox <trig id> --inbox-mode - Fast lane (optional, recommended). Messages reach the agent in about a second instead of
its poll interval, and the agent can poll less often. If the agent cannot read its webhook
routine's key,bridge.py checkprints the one command to run (it asks for the URL and key,
hidden, and stores themchmod 600). - Claude Code plugin. The agent installs the skill for you; you can also install it yourself:
/plugin install grok-bridge --marketplace Spoki-App/claude-grok-bridge - Instant answers in a terminal session (experimental). The plugin includes a Claude Code
channel: when the agent can reach your Mac (local
exec), its answer appears in your open session at once instead of waiting for a poll. Channels
are a research preview: start withclaude --dangerously-load-development-channels plugin:grok-bridge@claude-grok-bridge, terminal
only, and Team or Enterprise orgs need an Owner to enable channels. Verified live on 2026-10-19
(a dropped message showed up in an open session, which answered on its own); the agent's drop
through local exec from its poll routine is still to be checked. - Cloud sessions need the plugin enabled for the repository. Add to its
.claude/settings.json:{"extraKnownMarketplaces": {"claude-grok-bridge": {"source": {"source": "github", "repo": "Spoki-App/claude-grok-bridge"}}}, "enabledPlugins": {"grok-bridge@claude-grok-bridge": true}}.
They send through the inbox with their own login and get answers pushed back. No keys.
So they also know your agent by name, paste into the repository'sCLAUDE.mdtheFOR_REPO_CLAUDE_MDline thatpython3 -I ~/.claude/skills/grok-bridge/bridge.py peersprints. - No Claude CLI at all on the agent's box: give it a token scoped to the inbox routine
(claude.ai/code/routines, Edit, Add trigger, API) asCLAUDE_BRIDGE_INBOX_TOKEN.
How it works
sequenceDiagram
autonumber
participant H as You
participant C as Claude Code session
participant I as Claude inbox routine
participant G as Grok Bot agent
H->>C: "ask Grok Bot whether to merge develop now"
C->>I: runs the inbox with the question (own login)
G->>I: poll: collects messages addressed to it
Note over G: reads it as data,<br/>answers, or asks you first
G->>I: runs the inbox with the answer (Claude CLI on its box)
I->>C: pushes the answer into the asking session
C->>H: "Grok Bot answered: wait" (information, not approval)
The inbox is one Claude Code routine on your account and the bridge's only mailbox. Claude
sessions write to it with the login they already have; the agent reads it on a schedule and
answers through it; answers are pushed into the session that asked. Messages followclaude-grok-bridge/1:
| Command | Type | The agent replies |
|---|---|---|
ask |
question: a decision or context the agent owns |
answered, or escalated while it asks you |
tell |
request: a task you typed, with your exact words |
accepted then done, or needs_confirmation |
note |
note: FYI, either direction |
nothing |
(agent) ask Claude Code |
question to claude-code: a new cloud session answers, read-only |
answered |
Follow-ups stay in one conversation: ask Grok Bot ... --thread <first id>, and the agent reads the
thread before it answers.
Security
- Messages are data. Neither side follows instructions found inside one (tested with an
"ignore previous instructions" payload: logged, not obeyed). - Answers are not approvals. Claude Code still asks you before commits, merges, deploys or
messages. Pushed answers arrive marked "not user input". - Approvals stay with you. A relayed task touching money, production, merges or messages in
your name comes backneeds_confirmation, and the agent asks you. - Nothing extra to leak. Zero-touch uses only logins you already have. The inbox routine
has one connector (Claude_Code_Remote): no mail, drive or CRM. The optional fast-lane key
can only wake one routine and liveschmod 600on your Mac. - Verified delivery, audited models. Every send is checked in the inbox log. Every model in
the loop is checked against the actions it may take: a poll that tries anything but reading
stops with an alert. The inbox has no shell. - Pinned releases. Installs and updates come from the latest tagged release, never
main.
Report vulnerabilities privately: SECURITY.md.
Status
Verified on 2026-10-19 with a real Grok Bot agent: questions reached the agent in under a second
through the fast lane, it answered in about 15 s, the answer was in the Claude inbox about 30 s
after the question, and push into a cloud session took 1 to 2 minutes. Zero-touch sending
(through the inbox and the agent's poll) is new in 0.5.0; its end-to-end check is in progress.
The other direction (an agent asks Claude Code) was verified on the Claude side the same day: the
inbox scheduled an answering session that replied correctly about 2 minutes after the question,
with no approval needed; scheduled runs can start a few minutes late.
What it relies on. Some of it is preview or undocumented, so a platform change can break a
path without notice. The inbox log stays readable in claude.ai/code/routines in every case.
| Relies on | Status | If it changes |
|---|---|---|
| Claude Code routines and their fire API | research preview, documented | nothing moves; the core of the bridge |
Session reminders (create_trigger with persistent_session_id) for push into cloud sessions |
works, not in the public docs | answers stay in the inbox log; ask "did answer?" |
| Scheduled sessions asking approval for connector calls | observed, not documented | why answering sessions reply in their final message, not with a tool |
| Claude Code channels, development flag | research preview | the local channel stops; sessions check the inbox instead |
| Grok Bot routines, webhook trigger, local exec | Grok Bot features | poll interval or fast lane change; the setup line repairs it |
Each message is a short run on your Claude plan (30 per hour per routine). Claude.ai chat cannot
take part. A scheduled smoke test is planned (#1).
Compatibility. Until 1.0, minor versions may change commands. These are meant to stay: theclaude-grok-bridge/1 envelope (new fields are optional, readers ignore unknown ones), theask, tell, note, answer commands, the inbox's three output lines, and the one setup line.
1.0 comes after weeks of real use with no breaking change (#2).
FAQ
Why not a small relay server?You would run, secure and pay for a third service holding both sides' secrets. Both vendors
already have an authenticated way to wake an agent; the bridge only uses those.
It uses the Claude CLI already signed in on its box (many setups launch Claude Code that way),
only to run your inbox routine. A token scoped to that one routine works too.
It can send information into a session; the session still asks you before any side effect.
Tasks flow the other way: you tell Claude, Claude relays your words.
Any agent that can run a shell command, has a scheduled routine, and has the Claude CLI signed
in (or an inbox token) can be a peer: point it at grok/BOOTSTRAP.md, skip the Grok-only plugin
step, and set CLAUDE_BRIDGE_AGENT_KIND to its platform name. The protocol is plain JSON, and
the inbox pushes answers from any agent kind. Grok Bot is the first verified peer.
Roadmap
- Two-way messaging, push into the asking session, one-line setup and update
- Grok Bot plugin "Claude Code" (connector + skill)
- Zero-touch sending, no keys anywhere (verification in progress)
- Native Claude Code plugin (
/plugin install grok-bridge), cloud sessions via project settings - Threads: multi-turn conversations on one id
- Platform-neutral agent side (any agent with a shell, a schedule and the Claude CLI)
- Answers speak A2A (
state= A2ATaskState,thread=contextId) - Retries never deliver twice (the inbox dedupes by message id)
- Your agents' names, whatever they are, known to every Claude Code session
- Instant answers in local terminal sessions through a Claude Code channel (experimental)
- A second verified agent platform
Next, each tracked as an issue:
- Scheduled end-to-end smoke test (#1) and a clear list of the preview features it relies on (#5)
- Stable interface and a 1.0 after weeks of real use (#2)
- Answers in under a minute (#6), signed owner requests (#7), less logic in the inbox prompt (#8)
- Demo of the round trip (#3) and an unambiguous name (#4)
All open work: issues. Ideas: Discussions.
Contributing: CONTRIBUTING.md (layout, tests, the five pillars).
License
MIT. Not affiliated with Anthropic or xAI. Claude and Claude Code are trademarks of
Anthropic; Grok is a trademark of xAI.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found