Krok

Native iOS GUI for Grok Build (xAI's terminal coding agent). Local-first. Your code stays on your Mac.

Status: pre-alpha, in active development. See Docs/plans/2026-05-17-krok-v1-design.md for the v1 design and phased work plan.

Krok is a fork of remodex by Emanuele Di Pietro, licensed under Apache-2.0. Remodex does this for OpenAI's Codex CLI; Krok retargets the same architecture and the years of iOS-runtime hardening to xAI's Grok Build CLI. All credit for the architecture goes to Emanuele — we stand on his shoulders.

Architecture

┌──────────────┐    paired WS session   ┌───────────────┐    stdio/JSON-RPC    ┌──────────────┐
│  Krok        │ ◄────────────────────► │ krok-bridge   │ ◄──────────────────► │ grok CLI     │
│  iOS app     │   E2E encrypted        │  (Mac)        │   ACP protocol       │ (xAI)        │
└──────────────┘                        └───────────────┘                      └──────────────┘

Your iPhone is a steering wheel. The grok CLI runs on your Mac. Your xAI API key never leaves the Mac.

How it works

1. You run krok up on your Mac. A QR code and 8-character pairing code print to your terminal.
2. You scan the QR with the Krok iOS app (or paste the code manually).
3. The bridge spawns grok agent stdio and routes its JSON-RPC traffic to your phone over an end-to-end encrypted WebSocket.
4. Your phone sends prompts; grok runs them on your Mac; results stream back live.
5. Git commands you tap on the phone execute on the Mac. Your code stays put.

Prerequisites

• macOS with Node.js v18+
• xAI's grok CLI installed and authenticated:

  # Install grok (xAI's terminal agent)
  curl -L https://docs.x.ai/build/cli/install | sh
  grok login   # one-time browser auth

• iPhone or iPad on the same Wi-Fi as your Mac (cellular pairing requires a self-hosted relay — see Docs/self-hosting.md)
• Xcode 16+ if building the iOS app from source

Quick Start

1. Install the bridge

npm install -g krok-bridge

2. Run it

krok up

The bridge spawns grok agent stdio, starts an embedded relay on a random port, advertises itself via Bonjour as <your-hostname>.local, and prints a pairing QR + 8-character code.

3. Pair the iPhone

Open the Krok iOS app (built from source for now — see below), follow onboarding, and either scan the QR or paste the 8-character code. On the same Wi-Fi network, no further configuration is needed.

After the first scan:

• the iPhone saves the Mac as a trusted device
• the bridge keeps its identity locally
• subsequent launches reconnect automatically

Building the iOS app

Until Krok hits TestFlight or the App Store, you need to build it yourself in Xcode.

git clone https://github.com/parrisdigital/krok.git
cd krok/Krok
open Krok.xcodeproj

Target a simulator or your real device. Bundle ID is com.matthewparris.krok — Xcode will prompt for a signing team.

To build from the command line for a booted simulator:

SIM_ID=$(xcrun simctl list devices booted | awk '/Booted/ {print substr($NF,2,length($NF)-2); exit}')
xcodebuild build -project Krok/Krok.xcodeproj -scheme Krok \
  -destination "platform=iOS Simulator,id=$SIM_ID"
xcrun simctl install $SIM_ID \
  $HOME/Library/Developer/Xcode/DerivedData/Krok-*/Build/Products/Debug-iphonesimulator/Krok.app
xcrun simctl launch $SIM_ID com.matthewparris.krok

Commands

krok up

Starts Krok. Spawns the embedded relay if no KROK_RELAY is set, spawns grok agent stdio, prints a pairing QR.

krok start / krok restart / krok stop / krok status

macOS-only commands that manage the optional launchd background bridge service. The service keeps the bridge alive across terminal closes so trusted reconnect works hands-free.

krok reset-pairing

Clears saved pairing state. The next connection requires a fresh QR.

krok --version

Prints the installed bridge version.

Environment variables

For zero-config same-Wi-Fi pairing, you don't need any of these. They exist for self-hosting and advanced setups.

| Variable | Default | Description | |----------|---------|-------------| | KROK_RELAY | empty (uses embedded relay) | Override to point at a self-hosted public relay (wss://...) for cellular pairing | | KROK_PUSH_SERVICE_URL | disabled | Optional HTTP base URL for managed push registration/completion | | KROK_GROK_ENDPOINT | empty | Connect to an existing grok agent endpoint instead of spawning a local one |

Pairing and safety

• Local-first. grok runs on your Mac. All coding work happens there. The phone is a remote control.
• End-to-end encrypted. The bridge generates an Ed25519 identity on first boot. The pairing QR carries the relay URL, session ID, and bridge public key. After the X25519 handshake, application traffic is wrapped in AES-256-GCM with monotonic counters for replay protection.
• Embedded relay by default. krok up runs its own WebSocket relay on a random port. It only listens on your local network — not on the public internet.
• No bundled hosted relay. This package does not embed a developer-operated relay URL. If you want cellular pairing, run relay/ on a server you control and set KROK_RELAY.
• Re-pairing. If your iPhone changes (new device, restored backup), scan a fresh QR — the bridge auto-trusts the new pairing and forgets the old one.

Security model

The secure channel is built in these steps:

1. Bridge generates and persists a long-term Ed25519 identity keypair on the Mac.
2. The pairing QR shares the relay URL, session ID, bridge device ID, bridge identity public key, and a short expiry window.
3. iPhone and bridge exchange fresh X25519 ephemeral keys and nonces.
4. Bridge signs the handshake transcript with its Ed25519 identity key; iPhone verifies against the public key from the QR or the previously trusted Mac record.
5. iPhone signs a client-auth transcript with its own Ed25519 identity key; bridge verifies before accepting the session.
6. Both sides derive directional AES-256-GCM keys with HKDF-SHA256 and wrap application messages in encrypted envelopes with monotonic counters.

After the handshake, the transport layer can observe only connection metadata and the plaintext control messages used to set up the session.

Git integration

The bridge intercepts git/* JSON-RPC calls from the phone and runs them locally on your Mac:

| Command | Description | |---------|-------------| | git/status | Branch, tracking info, dirty state, file list, and diff | | git/commit | Commit staged changes with an optional message | | git/push | Push to remote | | git/pull | Pull from remote (auto-aborts on conflict) | | git/branches | List all branches with current/default markers | | git/checkout | Switch branches | | git/createBranch | Create and switch to a new branch | | git/log | Recent commit history | | git/stash / git/stashPop | Stash and pop working changes | | git/resetToRemote | Hard reset to remote (requires confirmation) | | git/remoteUrl | Get the remote URL and owner/repo |

Workspace integration

| Command | Description | |---------|-------------| | workspace/revertPatchPreview | Checks whether a reverse patch can be applied cleanly in the local repo | | workspace/revertPatchApply | Applies the reverse patch locally when the preview succeeds |

Connection resilience

• Auto-reconnect. Bridge reconnects with exponential backoff (1 s → 5 s max) when the session drops.
• Secure catch-up. A bounded local outbound buffer re-sends missed encrypted messages after reconnect.
• grok persistence. The grok process stays alive across transient session reconnects during the current bridge run.
• Graceful shutdown. SIGINT/SIGTERM cleanly close all connections.

FAQ

Do I need an xAI API key in Krok? No. The grok CLI handles xAI auth on the Mac. Krok itself never sees your key.

Does this work on Linux/Windows? The bridge runs on any OS that runs Node.js, but the daemon / trusted auto-reconnect path (launchd) is macOS-only. Same-Wi-Fi pairing works without a daemon; you just need to keep krok up running.

Can I pair over cellular? Not with the default setup. The embedded relay listens only on your local network. For cellular, run relay/ on a public server you control and set KROK_RELAY to its wss:// URL.

Can I self-host the relay? Yes — that's the intended path. See Docs/self-hosting.md. Krok does not depend on (and will never call out to) any third-party hosted relay by default.

Is the App Store version available? Not yet. Krok is pre-alpha. Build from source.

License and attribution

Apache License 2.0.

Krok is a fork of remodex by Emanuele Di Pietro. Architecture, transport hardening, and the long list of iOS-runtime quirk fixes inherited from remodex are all credit to Emanuele.

The Krok name and branding are this project's own. If you fork Krok, use a different app name and brand.