Grok Remote

Drive Grok Build from your phone or browser — live sessions, tools, history, and control on the same network as your PC.


Repo	https://github.com/Amnibro/grok-remote
Plugin	`/remote` · `/remote-stop` · `/remote-autostart`
Default theme	Grok (full greyscale) · dark
Safe demo	`http://host:2421/?demo=1` — no real chats, no agent
Companion	Optional `/xr` hologram — off until Settings → Apps → Companion
License	MIT

Companion model: High Poly Rikku by HumanContraband, CC BY 4.0. Clip JSON under clips/ is Mixamo-baked motion for that rig.

_{Desktop · Grok theme · demo data only}

Companion (`/xr`)

Opt-in hologram in your room (Quest browser or Preview on a 2D screen). Turn it on from Settings → Apps → Companion, then Open companion or the composer XR chip. Remote in the overlay returns to the text UI. Motion service is motion_service.py on port 2423.

python motion_service.py

Install

Windows desktop app (Tauri + WebView2) — wraps a running hub or starts one. Needs grok on PATH.

Product page: amni-scient.com/grok-remote
Portable: GrokRemote.exe
Setup: Grok Remote x64 setup

Hub plugin (phone + browser UI on :2421):

grok plugin install Amnibro/grok-remote --trust
grok plugin enable grok-remote

Pin a release:

grok plugin install Amnibro/grok-remote@v1.11.0 --trust

In the TUI, reload plugins if needed (/plugins → r), then:

/remote

Open the printed URL on your phone (same Wi‑Fi), e.g. http://192.168.x.x:2421/?auto=1.

Linux (Arch, Debian/Ubuntu, Fedora, openSUSE…) / macOS:

git clone https://github.com/Amnibro/grok-remote && cd grok-remote
python3 grok_remote_ctl.py doctor          # checks python, aiohttp, grok, firewall, voice; prints the fix for your distro
python3 grok_remote_ctl.py install --pin   # app-menu launcher + icon + `grok-remote` CLI, pinned to the taskbar/dock
grok-remote autostart boot                 # optional: start at login (systemd user unit / LaunchAgent)
grok-remote open                           # starts the hub if needed and opens the desktop window
grok-remote url --qr                       # phone pairing link + QR in the terminal

./start.sh still works on its own. On distros whose system Python is externally managed (Arch, Debian 12+, Fedora), it uses python-aiohttp from your package manager when present, otherwise it builds a private venv under ~/.grok/plugin-data/grok-remote/venv and leaves the system Python alone. Pinning is automatic on KDE Plasma, GNOME and Cinnamon; other desktops get instructions. If phones can't connect, doctor prints the ufw/firewalld line that opens port 2421.

`grok-remote …`
`start` · `stop` · `restart` · `status`	hub lifecycle (`stop` never touches other grok processes)
`install [--pin] [--autostart]` · `uninstall` · `pin [--off]`	launcher, taskbar/dock pin
`autostart on\|boot\|off\|status`	Grok SessionStart hook, start at login
`url [--qr]` · `open [--browser]` · `doctor`	pairing, window, diagnostics

Product tour

All images below use ?demo=1 sample sessions (titles like Ship remote cockpit polish) — not personal chats or real paths.

Desktop cockpit (Grok)

Sessions rail + live feed + composer. Tool cards show syntax-colored edits.

Command deck (☰)

Top-right control opens the Command deck: Skills, New task, delivery mode, permission cycle, Tools (Todos / Terminal / Git / Export…), hide/collapse grids, apps, theme, tour.

Special tools in the deck

Scroll the deck for specials — path attach, todos, terminal, git diff, export. (Composer + is attach-only.)

Link control (orbit)

Planet control: Start server, Stop remote, health — without killing your desktop TUI.

Skills & slash commands

Skills sheet merges agent commands + disk skills. Remote also intercepts /effort and /loop (hub scheduler — no CLI window required).

Setup & theme gallery

Pick Grok, product accents, or fun skins × light/dark.

Grok (default)	Amni-Scient	Matrix

Ubuntu	Commodore	Grok light

Spoiler mode

Blur titles, paths, and IDs for safe sharing. Desktop: hold Alt to peek. Phone: private-screen badge.

Phone

Chat (Grok)	Command deck	Spoiler	Scient skin

Features

Area	What you get
Sessions	List, open, archive (device-local), live vs historical
History	Disk-first chat paint; scroll up for older turns; clean You bubbles (no instruction chrome)
Live stream	ACP updates + disk catch-up for PC-side prompts
Composer	Attach (+), Mic / XR, Interject · Queue · FYI when busy, Cancel
Command deck	Skills, task, permission cycle, tools, hide/collapse, IDE, persona, watch, Delve, theme, tour
Orbit	Start / stop remote stack + health
`/effort`	`low` · `medium` · `high` · `xhigh` (livebar chip or slash)
`/loop`	Hub scheduler — fires on the open session without a CLI window; `/loops` · `/loop stop`
Skills	Agent + disk skill palette
Themes	Grok greyscale default + Scient + retro gallery
Spoiler	Privacy blur for screenshots
Desktop app	Optional Tauri window (`GrokRemote.exe`, or `grok-remote-desktop` on Linux) wrapping the same hub as the phone
Install & pin	Command deck → Install app… or `grok-remote install --pin`: app menu, taskbar/dock pin, start at login

Quick start

From Grok Build

/remote

Manual

cd path\to\grok-remote
.\start.ps1 -Cwd path\to\your\project

Desktop app (Windows)

Download GrokRemote.exe or build:

cd desktop-tauri
npm install
npm run build

Details: desktop-tauri/README.md

Architecture

Phone / browser  ──HTTP──►  UI + hub  :2421
                 ──WS /ws─►  multi-client hub  ──►  grok agent serve  127.0.0.1:2419
                                                         │
                                                    tools / files on PC

Hub fans out one agent to many clients (phone + desktop).
/loop jobs live under ~/.grok/plugin-data/grok-remote/loops.json and fire via the hub.
Prefer same Wi‑Fi / VPN; don’t expose the agent to the open internet without care.

Auto-start (optional)

powershell -File .\scripts\install-autostart.ps1 -Cwd path\to\project
powershell -File .\scripts\install-autostart.ps1 -Boot -Cwd path\to\project
powershell -File .\scripts\install-autostart.ps1 -Disable

Linux / macOS: grok-remote autostart on|boot|off|status (boot installs a systemd user unit or LaunchAgent).

Or in TUI: /remote-autostart on · boot · off · status

Config: ~/.grok/plugin-data/grok-remote/config.json (default off).

Safety

Never Stop-Process -Name grok (kills every Grok session on the machine).
/remote-stop only stops remote UI + remote agent serve.
Public docs and screenshots use ?demo=1 only — no real session titles or machine paths.

Develop & screenshots

.\start.ps1 -Cwd .
# then, with UI on :2421:
node scripts/capture-screenshots.mjs

Writes docs/screenshots/*.png from demo mode (Grok + theme gallery + phone). Requires Chrome + playwright-core.

See CONTRIBUTING.md and architecture_map.md.

Docs

Doc	Purpose
PUBLISH.md	Plugin install & marketplaces
skills/remote/SKILL.md	`/remote` skill
changelog.md	Release notes
architecture_map.md	Layout & privacy

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
android-wear		android-wear
archive/electron-desktop		archive/electron-desktop
brains		brains
clips		clips
commands		commands
desktop-tauri		desktop-tauri
desktop		desktop
docs		docs
hooks		hooks
scripts		scripts
skills/remote		skills/remote
tests		tests
tools		tools
web		web
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PUBLISH.md		PUBLISH.md
README.md		README.md
_probe_acp.py		_probe_acp.py
architecture_map.md		architecture_map.md
changelog.md		changelog.md
clip-invariants.py		clip-invariants.py
companion.py		companion.py
companion_env.py		companion_env.py
config.default.json		config.default.json
gesture-queue.sh		gesture-queue.sh
grok_remote_ctl.py		grok_remote_ctl.py
install-local.ps1		install-local.ps1
motion_service.py		motion_service.py
nostr_bridge.py		nostr_bridge.py
package.json		package.json
pairing.py		pairing.py
public_net.py		public_net.py
remote_auth.py		remote_auth.py
room.py		room.py
run-motion.cmd		run-motion.cmd
server.py		server.py
start.ps1		start.ps1
start.sh		start.sh
work_board.py		work_board.py

Navigation Menu

Repository navigation

About

Repository files navigation

Grok Remote

Companion (`/xr`)

Install

Product tour

Desktop cockpit (Grok)

Command deck (☰)

Special tools in the deck

Link control (orbit)

Skills & slash commands

Setup & theme gallery

Spoiler mode

Phone

Features

Quick start

From Grok Build

Manual

Desktop app (Windows)

Architecture

Auto-start (optional)

Safety

Develop & screenshots

Docs

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Grok Remote

Companion (/xr)

Install

Product tour

Desktop cockpit (Grok)

Command deck (☰)

Special tools in the deck

Link control (orbit)

Skills & slash commands

Setup & theme gallery

Spoiler mode

Phone

Features

Quick start

From Grok Build

Manual

Desktop app (Windows)

Architecture

Auto-start (optional)

Safety

Develop & screenshots

Docs

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Companion (`/xr`)