detached 82191b3

Add Build Remote Agent phone pairing

Document the optional Build Remote Agent phone pairing setup and MCP configuration.

Co-authored-by: LinespottingPrivate <149178915+user@users.noreply.github.com>
commit
82191b33a9d54993ce9c85988dc250421623b75b
author
Owner of LinespottingOrg · · 2026-08-24 05:59 UTC
committer
GitHub · · 2026-08-24 05:59 UTC
parent
2470fda
signature
GPG UnverifiedB5690EEEBB952194 The key is unknown
refs
tag: v0.3.50
1 file · +69 -0
Unified
UnifiedSplit
M examples/extensions/mcp-bridge/README.md +69 -0
@@ -58,6 +58,65 @@ This extension reads MCP server configurations from standard locations (same for
5858
5959 The model initially sees one small loader tool, `mcp__search_tools`. It searches cached MCP tool names and descriptions locally, activates up to eight relevant definitions by default, and then calls the selected MCP tool normally. This keeps large MCP installations compatible with providers that limit request or tool-schema size.
6060
61+### Phone pairing with Build Remote Agent
62+
63+[Build Remote Agent](https://grokbuildremote.com/) is an optional, third-party integration that lets a paired phone observe terminal sessions and veto actions. It is an independent Linespotting AB product and is not affiliated with xAI or SpaceX.
64+
65+#### Install the agent
66+
67+Pin release `v0.6.0` and verify the binary against the checksum listed here. The release's own `SHA256SUMS` file does not currently match five of its six binary assets, so do not use that file as the trust source. These checksums were verified directly against the release assets on 2026-08-24:
68+
69+```text
70+62673a6856342a87d4a2a659bc1de92200aa19a5b60d88d252254940820f0b7f gbr-agent-darwin-amd64
71+7baa1a8e214cd71b60e3f2b5063713e00ff740939749c3cab3d702784a1432f8 gbr-agent-darwin-arm64
72+fb54724367882497f2e8e05e40ecdeb4be29e008e6c865fc5c426cf464e6ad6e gbr-agent-linux-amd64
73+9e9d7ca45bb0c4ded9d04226136013e9b64ae30f16bcf03069d35e9c38171cb9 gbr-agent-linux-arm64
74+40355b2be6cd68f3be68f2a06dfd30307ec1a60f16f87f1d6174012b35aa4a49 gbr-agent-windows-amd64.exe
75+8fb9efcbc7e2ac91c11964944bf0f45e31bb23f4356d9dcb4b305d7cb9b0fe8c gbr-agent-windows-arm64.exe
76+```
77+
78+This macOS Apple Silicon example downloads, verifies, and installs the binary. Change both `ASSET` and `SHA` for another platform.
79+
80+```bash
81+VER=v0.6.0
82+ASSET=gbr-agent-darwin-arm64
83+SHA=7baa1a8e214cd71b60e3f2b5063713e00ff740939749c3cab3d702784a1432f8
84+BASE="https://github.com/LinespottingOrg/GrokBuildRemote-Agents/releases/download/$VER"
85+curl -fsSL -o "$ASSET" "$BASE/$ASSET"
86+if command -v sha256sum >/dev/null 2>&1; then
87+ printf '%s %s\n' "$SHA" "$ASSET" | sha256sum -c -
88+else
89+ printf '%s %s\n' "$SHA" "$ASSET" | shasum -a 256 -c -
90+fi
91+mkdir -p "$HOME/.local/bin"
92+install -m 0755 "$ASSET" "$HOME/.local/bin/gbr-agent"
93+export PATH="$HOME/.local/bin:$PATH"
94+gbr-agent version # must report v0.6.0
95+gbr-agent pair
96+gbr-agent run
97+```
98+
99+Keep `gbr-agent run` running. Its Bot API should only be available over loopback:
100+
101+```bash
102+curl -sS http://127.0.0.1:8788/health
103+curl -sS http://127.0.0.1:8788/v1/sessions
104+```
105+
106+#### Install the MCP server
107+
108+The MCP server requires Node.js 20 or newer. Pin its source instead of cloning the mutable default branch:
109+
110+```bash
111+git clone --branch v0.6.0 --depth 1 https://github.com/LinespottingOrg/GrokBuildRemote-Agents.git
112+cd GrokBuildRemote-Agents/mcp/gbr-mcp
113+npm install --ignore-scripts
114+MCP_PATH="$(pwd)/bin/gbr-mcp.js"
115+node "$MCP_PATH" --diagnose
116+```
117+
118+The `v0.6.0` source does not include a package lock, so its npm dependency resolution is not fully reproducible. Review the package manifest and resolved dependency tree before use. Put the absolute value of `MCP_PATH` in the configuration below. Never put mailbox keys in `mcp.json`.
119+
61120 ## Configuration
62121
63122 Config files are loaded from two locations (project overrides global per-server):
@@ -86,6 +145,13 @@ Standard MCP config — same as Claude Desktop, with zot-specific extensions:
86145 "idleTimeout": 300 // idle timeout before stopping (seconds)
87146 },
88147
148+ // Build Remote Agent (gbr/1). Pair with `gbr-agent pair`, then keep
149+ // `gbr-agent run` running. Use an absolute path to the pinned MCP checkout.
150+ "gbr": {
151+ "command": "node",
152+ "args": ["/ABSOLUTE/PATH/GrokBuildRemote-Agents/mcp/gbr-mcp/bin/gbr-mcp.js"]
153+ },
154+
89155 // ── Streamable HTTP transport (modern HTTP) ─────────────────────────────
90156 "supabase": {
91157 "transport": "streamable-http",
@@ -289,3 +355,6 @@ Tested MCP servers:
289355
290356 Note: grep.app uses the root endpoint `/`. Streamable HTTP protocol headers are handled automatically by the bridge and should not be written to `mcp.json`.
291357
358+## What the paired phone sees
359+
360+Build Remote Agent exposes terminal windows on the machine. Its loopback `:8788` endpoint is a Bot API that returns JSON, not an MCP endpoint or terminal transcript. See the third-party's [current phone visibility documentation](https://github.com/LinespottingOrg/GrokBuildRemote-Agents/blob/main/docs/WHAT-THE-PHONE-SEES.md) for details.
@@ -58,6 +58,65 @@ This extension reads MCP server configurations from standard locations (same for
58 58
59 The model initially sees one small loader tool, `mcp__search_tools`. It searches cached MCP tool names and descriptions locally, activates up to eight relevant definitions by default, and then calls the selected MCP tool normally. This keeps large MCP installations compatible with providers that limit request or tool-schema size.59 The model initially sees one small loader tool, `mcp__search_tools`. It searches cached MCP tool names and descriptions locally, activates up to eight relevant definitions by default, and then calls the selected MCP tool normally. This keeps large MCP installations compatible with providers that limit request or tool-schema size.
60 60
61+### Phone pairing with Build Remote Agent
62+
63+[Build Remote Agent](https://grokbuildremote.com/) is an optional, third-party integration that lets a paired phone observe terminal sessions and veto actions. It is an independent Linespotting AB product and is not affiliated with xAI or SpaceX.
64+
65+#### Install the agent
66+
67+Pin release `v0.6.0` and verify the binary against the checksum listed here. The release's own `SHA256SUMS` file does not currently match five of its six binary assets, so do not use that file as the trust source. These checksums were verified directly against the release assets on 2026-08-24:
68+
69+```text
70+62673a6856342a87d4a2a659bc1de92200aa19a5b60d88d252254940820f0b7f gbr-agent-darwin-amd64
71+7baa1a8e214cd71b60e3f2b5063713e00ff740939749c3cab3d702784a1432f8 gbr-agent-darwin-arm64
72+fb54724367882497f2e8e05e40ecdeb4be29e008e6c865fc5c426cf464e6ad6e gbr-agent-linux-amd64
73+9e9d7ca45bb0c4ded9d04226136013e9b64ae30f16bcf03069d35e9c38171cb9 gbr-agent-linux-arm64
74+40355b2be6cd68f3be68f2a06dfd30307ec1a60f16f87f1d6174012b35aa4a49 gbr-agent-windows-amd64.exe
75+8fb9efcbc7e2ac91c11964944bf0f45e31bb23f4356d9dcb4b305d7cb9b0fe8c gbr-agent-windows-arm64.exe
76+```
77+
78+This macOS Apple Silicon example downloads, verifies, and installs the binary. Change both `ASSET` and `SHA` for another platform.
79+
80+```bash
81+VER=v0.6.0
82+ASSET=gbr-agent-darwin-arm64
83+SHA=7baa1a8e214cd71b60e3f2b5063713e00ff740939749c3cab3d702784a1432f8
84+BASE="https://github.com/LinespottingOrg/GrokBuildRemote-Agents/releases/download/$VER"
85+curl -fsSL -o "$ASSET" "$BASE/$ASSET"
86+if command -v sha256sum >/dev/null 2>&1; then
87+ printf '%s %s\n' "$SHA" "$ASSET" | sha256sum -c -
88+else
89+ printf '%s %s\n' "$SHA" "$ASSET" | shasum -a 256 -c -
90+fi
91+mkdir -p "$HOME/.local/bin"
92+install -m 0755 "$ASSET" "$HOME/.local/bin/gbr-agent"
93+export PATH="$HOME/.local/bin:$PATH"
94+gbr-agent version # must report v0.6.0
95+gbr-agent pair
96+gbr-agent run
97+```
98+
99+Keep `gbr-agent run` running. Its Bot API should only be available over loopback:
100+
101+```bash
102+curl -sS http://127.0.0.1:8788/health
103+curl -sS http://127.0.0.1:8788/v1/sessions
104+```
105+
106+#### Install the MCP server
107+
108+The MCP server requires Node.js 20 or newer. Pin its source instead of cloning the mutable default branch:
109+
110+```bash
111+git clone --branch v0.6.0 --depth 1 https://github.com/LinespottingOrg/GrokBuildRemote-Agents.git
112+cd GrokBuildRemote-Agents/mcp/gbr-mcp
113+npm install --ignore-scripts
114+MCP_PATH="$(pwd)/bin/gbr-mcp.js"
115+node "$MCP_PATH" --diagnose
116+```
117+
118+The `v0.6.0` source does not include a package lock, so its npm dependency resolution is not fully reproducible. Review the package manifest and resolved dependency tree before use. Put the absolute value of `MCP_PATH` in the configuration below. Never put mailbox keys in `mcp.json`.
119+
61 ## Configuration120 ## Configuration
62 121
63 Config files are loaded from two locations (project overrides global per-server):122 Config files are loaded from two locations (project overrides global per-server):
@@ -86,6 +145,13 @@ Standard MCP config — same as Claude Desktop, with zot-specific extensions:
86 "idleTimeout": 300 // idle timeout before stopping (seconds)145 "idleTimeout": 300 // idle timeout before stopping (seconds)
87 },146 },
88 147
148+ // Build Remote Agent (gbr/1). Pair with `gbr-agent pair`, then keep
149+ // `gbr-agent run` running. Use an absolute path to the pinned MCP checkout.
150+ "gbr": {
151+ "command": "node",
152+ "args": ["/ABSOLUTE/PATH/GrokBuildRemote-Agents/mcp/gbr-mcp/bin/gbr-mcp.js"]
153+ },
154+
89 // ── Streamable HTTP transport (modern HTTP) ─────────────────────────────155 // ── Streamable HTTP transport (modern HTTP) ─────────────────────────────
90 "supabase": {156 "supabase": {
91 "transport": "streamable-http",157 "transport": "streamable-http",
@@ -289,3 +355,6 @@ Tested MCP servers:
289 355
290 Note: grep.app uses the root endpoint `/`. Streamable HTTP protocol headers are handled automatically by the bridge and should not be written to `mcp.json`.356 Note: grep.app uses the root endpoint `/`. Streamable HTTP protocol headers are handled automatically by the bridge and should not be written to `mcp.json`.
291 357
358+## What the paired phone sees
359+
360+Build Remote Agent exposes terminal windows on the machine. Its loopback `:8788` endpoint is a Bot API that returns JSON, not an MCP endpoint or terminal transcript. See the third-party's [current phone visibility documentation](https://github.com/LinespottingOrg/GrokBuildRemote-Agents/blob/main/docs/WHAT-THE-PHONE-SEES.md) for details.

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 1

Tags 476

↑↓ moveenter openesc close