Skip to main content
plugin CX Codex

build-remote-agent — Claude Code plugin: what it does, how to install

build-remote-agent pairs local coding sessions with a phone via the gbr-agent binary. Lets you watch terminal output and send input without opening incoming firewall ports.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install build-remote-agent@awesome-codex-plugins
Open on GitHub

What build-remote-agent does

The plugin interfaces with the local gbr-agent desktop binary over the gbr/1 protocol or 127.0.0.1:8788. It discovers active terminal sessions, captures console output, and routes input from paired mobile devices. Pairing runs through gbr-agent pair, which displays an onboarding QR code in your browser.

Connection architecture relies on outbound HTTPS over port 443, so your network requires no port forwarding. While the desktop gbr-agent is open source under MIT, the companion mobile apps are proprietary and cost $13. The plugin will not function without the companion desktop binary running on Windows, macOS, or Linux.

What it helps with

  • monitor terminal sessions from a phone in real time
  • inject input into local CLI sessions remotely
  • establish remote session viewing without open inbound ports

Example prompts for the agent

  • Attach the active session to gbr-agent at 127.0.0.1:8788
  • Check connection reachability using gbr-agent netcheck

How to install build-remote-agent

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install build-remote-agent@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about build-remote-agent

How to install build-remote-agent in Claude Code?

Run /plugin marketplace add hashgraph-online/awesome-codex-plugins and then /plugin install build-remote-agent@awesome-codex-plugins.

What does build-remote-agent do?

It relays terminal input and output between your workstation and a spectator phone using the desktop gbr-agent binary.

Are the mobile apps open source?

No. The desktop binary is open-source MIT software, but the iOS and Android mobile apps are closed-source commercial tools costing $13.

Source text

GrokBuildRemote-Agents · MIT
# Build Remote Agent — desktop (`gbr-agent`)

**Product brand:** Build Remote Agent  
**Binary:** `gbr-agent` **v0.6.2**  
**License:** **MIT** (open source)  
**Org:** LinespottingOrg / Linespotting AB  

### Docs (humans + AIs)

| Read this | When |
|-----------|------|
| **[INSTALL.md](INSTALL.md)** | AIs first: install, pair, `mcp add`, Bot API `:8788` |
| **[AGENTS.md](AGENTS.md)** | You are an AI installing or debugging |
| **[mcp/gbr-mcp/INSTALL.md](mcp/gbr-mcp/INSTALL.md)** | Claude / Grok CLI / Cursor / Hermes / OpenClaw |
| **[FAQ.md](FAQ.md)** | Same FAQ as the website (humans + AIs + schema) |
| **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** | Something failed (401, empty sessions, stale names) |
| **[SESSION-NAMES.md](SESSION-NAMES.md)** | Six identical titles / rename / 255 sessions |
| **[NETWORK.md](NETWORK.md)** | Firewall / netcheck |
| **[docs/BOT-API.md](docs/BOT-API.md)** | Grok bot / HTTP API (localhost + relay) |
| **[llms.txt](llms.txt)** | Short machine summary |
| **[COMPATIBILITY.md](COMPATIBILITY.md)** | What the phone sees; plugins |
| **[plugins/README.md](plugins/README.md)** | Our plugin registry (not someone else’s) |
| **[docs/PINNED-INSTALL.md](docs/PINNED-INSTALL.md)** | GitHub Release + SHA-256 |
| **[docs/WHAT-THE-PHONE-SEES.md](docs/WHAT-THE-PHONE-SEES.md)** | Terminals vs headless |
| **[SECURITY.md](SECURITY.md)** | Mailbox = machine roster |
| https://grokbuildremote.com/support | End-user playbook |  

Desktop agents for **Windows**, **macOS**, and **Linux**. They discover local terminal / **Grok Build** sessions, inject input, capture output, and exchange **protocol `gbr/1`** envelopes over HTTPS — your phone and PC never open ports to each other.

This agent pairs with the paid **Build Remote Agent** mobile apps ($13 one-time). The mobile clients are **not** open source; this desktop agent **is**.

| App | Link |
|-----|------|
| **Website** | https://grokbuildremote.com/ |
| **iOS / iPad / Mac / Vision** | https://apps.apple.com/app/id6791293726 |
| **Android (Google Play)** | https://play.google.com/store/apps/details?id=com.grokbuildremote.app |

### Why it exists

Grok Build (SpaceX / xAI agentic coding CLI) gained a new interface and API surface around **16 July 2026**. That made remote control of *local* Grok Build sessions practical. This open-source agent + paid mobile remote implements that workflow. Independent product — not affiliated with SpaceX or xAI except as a client of public APIs / open tooling.

---


## Independence & trademarks

**Build Remote Agent is an independent, third-party product from Linespotting AB.**
It is **not** affiliated with, endorsed by, or sponsored by **xAI** or **SpaceX**, and it is
**not** covered by the **Grok** trademark or brand. "Grok" and "Grok Build" are used solely to
describe compatibility with the user's own locally installed Grok Build CLI.

- **Desktop agent (this repo): 100% open source** under the MIT license.
- **Mobile apps ("Build Remote Agent" on iOS / Android): separate commercial products**, closed source (private repository), sold by Linespotting AB.

## Open source

| What | Policy |
|------|--------|
| Source (`cmd/`, `internal/`, this repo) | **Public · MIT** |
| Official binaries | Free for end users |
| Mobile apps | Separate private repo; paid $13 |

**Repo:** https://github.com/LinespottingOrg/GrokBuildRemote-Agents  
**Website:** https://grokbuildremote.com/

---

## Free download

- **Website:** https://grokbuildremote.com/#download  
- **GitHub Releases:** tagged `v*` assets  
- **Clone & build:** see below  

| File | Platform |
|------|----------|
| `gbr-agent-windows-amd64.exe` | Windows x64 |
| `gbr-agent-darwin-amd64` | macOS Intel |
| `gbr-agent-darwin-arm64` | macOS Apple Silicon |
| `gbr-agent-linux-amd64` | Linux x64 |
| `gbr-agent-linux-arm64` | Linux ARM64 |

---

## Quick install

**Preferred:** checksum **the installer**, then the binary — [docs/PINNED-INSTALL.md](docs/PINNED-INSTALL.md).

`curl https://grokbuildremote.com/install.sh | bash` is a **mutable remote install**. Do not paste it into other projects’ official docs.

### macOS / Linux (pinned)

```bash
VER=v0.6.2
BASE=https://github.com/LinespottingOrg/GrokBuildRemote-Agents/releases/download/$VER
SHA=0a7963dc668750bfcb907bb72f6f6f8db30881b02636e417e08e102352309301
curl -fsSL -o /tmp/gbr-install.sh "$BASE/install.sh"
echo "$SHA  /tmp/gbr-install.sh" | shasum -a 256 -c -
bash /tmp/gbr-install.sh
```

### Windows PowerShell (pinned)

```powershell
$ver = "v0.6.2"
$sha = "b604a21b5dae5a874487a597778d15742b3c2afb2470c93a8e8ba0a76e486cdf"
$base = "https://github.com/LinespottingOrg/GrokBuildRemote-Agents/releases/download/$ver"
$i = Join-Path $env:TEMP "gbr-install.ps1"
Invoke-WebRequest "$base/install.ps1" -OutFile $i -UseBasicParsing
if ((Get-FileHash $i -Algorithm SHA256).Hash.ToLowerInvariant() -ne $sha) { throw "installer SHA-256 mismatch" }
& $i
```

### From source

```bash
git clone --branch v0.6.2 --depth 1 https://github.com/LinespottingOrg/GrokBuildRemote-Agents.git
cd GrokBuildRemote-Agents
# build per Makefile / go build in cmd/
```

Default install locations:

| OS | Directory |
|----|-----------|
| macOS / Linux | `~/.local/bin/gbr-agent` |
| Windows (user) | `%LOCALAPPDATA%\GrokBuildRemote\gbr-agent.exe` |

### Typical flow

```bash
gbr-agent pair
# opens browser QR — scan with the phone camera
# legacy: gbr-agent pair -code YOURCODE

# Firewall / VPN / ports (no inbound ports — outbound HTTPS 443 only)
gbr-agent netcheck
gbr-agent netcheck -doc
# See NETWORK.md
gbr-agent run

# Optional: start at login in background (after pair)
gbr-agent service install
gbr-agent service status

# Fleet remote (this machine is driven by another hub, no phone):
gbr-agent pair-as-mailbox -name mac
gbr-agent service install
# On the hub, later: gbr-agent fleet add -name mac -os darwin
```

### Self-hosted relay

Optional — most users keep the production Worker. See **[SELF-HOSTED-RELAY.md](SELF-HOSTED-RELAY.md)**.

```bash
export GBR_RELAY_URL=https://your-worker.workers.dev
gbr-agent pair && gbr-agent run
# same URL in phone Settings → Relay
```

### What’s new in 0.5.1

- Dynamic session roster: pushed `list` with `replace: true` + `reason: "snapshot"`, and `heartbeat.payload.sessions[]` (`session_id` + `title`)
- No six-session cap — soft max **255** (extras dropped with a log, never crash); Grok Build is sorted first
- `gbr-agent rename -session ID -name "Phone title"` updates the live title without restart
- Later `register` envelopes update the title for an existing id
- Relay 0.5.1 latest-wins (one register per session, one list, one heartbeat)

### What’s new in 0.5.0

- Richer heartbeat (`agent_version`, `relay`, `os`) for phone session health  
- `service install` messaging + embed `GBR_RELAY_URL` into LaunchAgent / systemd when set  
- Service working directory = user home (avoids synthetic `dist` sessions)  
- Feedback peeks (0.4.5+) unchanged; inject/pair protocol still `gbr/1`  

Optional: `sessions`, `status`, `version`, `rename -name MyPC`.

### Session names

The phone shows a **title**, not the raw `conhost` / folder slug. See **[SESSION-NAMES.md](SESSION-NAMES.md)**.

```text
/rename Phone Grok                  # in Grok Build (slash command)
gbr-agent sessions                  # list grok-build-… ids
gbr-agent rename -session grok-build-40a22 -name "Phone Grok"
```

Soft max 255 advertised sessions; Grok is first. The app must apply `list.replace` / `heartbeat.sessions` (issue #3).

### API key

Agent may read relay / model API credentials from env (`GBR_API_KEY`, `XAI_API_KEY`, etc.) or local config under `~/.gbr/` — see support docs on the website.

---

## Contributing

Issues and PRs welcome on GitHub. Please keep protocol `gbr/1` compatibility stable unless versioned intentionally.

## Licensing note

This desktop agent is MIT-licensed and free. The companion **mobile apps**
("Build Remote Agent") are separate commercial products and are not covered
by this repository's MIT license.

© Linespotting AB · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set391

The whole set →
canvas-apps-plugin-codex canvas-apps-plugin-codex is a Codex CLI plugin that creates and edits Power Apps Canvas apps from plain-text descriptions, syncing files to an open Studio session. CX Codex ★ 1,596repo stars calle Connects the CALL-E CLI to plan, execute, and monitor automated phone calls directly from your AI coding environment. CX Codex ★ 1,596repo stars burpsuite-mcp-bridge burpsuite-mcp-bridge is a Claude Code plugin that connects Burp Suite workflows over MCP to search traffic, replay requests with bounded changes, and export evidence. CX Codex ★ 1,596repo stars bulktranscripts bulktranscripts — a hosted MCP server that pulls YouTube captions for a single video, a whole channel or a playlist and hands them to your agent as text. It also searches YouTube and watches for new uploads. CX Codex ★ 1,596repo stars bkt The bkt plugin for Claude Code and Codex gives agents access to Bitbucket Cloud and Data Center repositories and pull requests, with machine-readable command output. CX Codex ★ 1,596repo stars bankbridge Wires the BankBridge remote MCP server into Claude so the agent can read your US bank, card and brokerage accounts and answer spending questions from live data. CX Codex ★ 1,596repo stars babeldoc-pdf-translate babeldoc-pdf-translate translates PDF files while preserving the original visual layout using a local BabelDOC engine, custom glossaries, and bilingual output. CX Codex ★ 1,596repo stars axonflow axonflow is a Claude Code plugin that checks Codex actions against policies, detects PII and secrets, and records audit events. Blocked calls get a decision_id. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open