grok-bot-0.18-reconstructed README

The project's README from github.com/b-nnett/grok-bot-0.18-reconstructed. As one markdown file: README.md.

Grok Bot 0.18 — reconstructed and extended

Grok Bot Router settings with Codex selected and local usage totals

This repository is an unofficial, source-oriented reconstruction of the publicly shipped Grok Bot 0.18.0 macOS app.

The project began as an attempt to understand how the desktop app was put together. It now contains readable TypeScript implementations of its Electron, host, coordinator, local-execution, protocol, and renderer boundaries, plus a deterministic toolchain for turning those sources back into a working macOS application.

It also adds a few practical experiments:

This is a hacking and research project, not Anysphere's original monorepo and not an official Grok Bot release. Names and module boundaries inferred from a compiled application may differ from the original source.

What is in the repository?

The checked-in tree contains the reviewed reconstruction, tests, manifests, build scripts, and Git LFS preservation copies of the original macOS arm64 and Windows x64 installers. It deliberately does not commit the extracted upstream application, build output, local credentials, or the large forensic recovery workspace.

The public Grok Bot 0.18.0 application is instead treated as a pinned build input. During bootstrap, the toolchain downloads it, verifies its SHA-256 identity, and extracts the pieces required to assemble the reconstruction.

The resulting app is a hybrid by design:

The upstream app installed on the machine is never overwritten.

Why retain the shipped renderer?

The distributed application did not include the original frontend source or source maps. It contained optimized, minified production JavaScript and CSS chunks: enough to inspect behavior and recover contracts, but not the authored React components, names, comments, file structure, or design-system source.

Recreating the complete frontend with the same polish and behavior would have been a separate, much larger reverse-engineering project. It was not a realistic goal for a weekend build. The practical choice was therefore to reconstruct the runtime and control-plane code, retain the checksum-pinned shipped renderer, and make the smallest auditable UI patch needed for the new Router settings.

frontend/ is a readable partial reconstruction and design workspace. It is useful for understanding UI contracts and experimenting with clean components, but it should not be mistaken for Anysphere's missing original frontend source or a pixel-perfect replacement for the packaged renderer.

Preserved original installers

Research copies of the exact 0.18.0 installers live under research-archives/original/0.18.0/ and are stored with Git LFS:

Platform File SHA-256
macOS arm64 macos-arm64/Grok_Bot_0.18.0.dmg a253ccd8aab01e083f9812a0264354c5034d8ba7f0610bbb557e82ae77d203eb
Windows x64 windows-x64/Grok_Bot_0.18.0_Setup.exe 464079a15ef5fa8b61ccea8fffcc78f63cfcf6df65fb0ad5e725d8b95f7e437e

See research-archives/README.md for source URLs, sizes, verification commands, and the machine-readable artifact manifest.

Current features

Inference Router

Open Settings → Router to choose the backend used for new turns:

Provider Authentication Tool support
Cursor Existing Grok Bot/Cursor session Native Grok Bot tools and plugins
Claude Code Existing Claude Code login Routed Grok Bot MCP tools
Codex Existing local ChatGPT/Codex login Direct Responses transport with Grok Bot tools
OpenRouter API key saved through the desktop secrets bridge Grok Bot tool-execution loop

Cursor is the default. Claude Code and Codex do not require separate API keys when their local clients are already authenticated. The application preserves streaming responses, thinking state, reactions, rich plugin mentions, and MCP tool execution across routed conversations.

Usage & Billing shows the locally recorded request and token totals for providers that return usage data. These figures are activity records, not an authoritative provider invoice.

Local Docker sandbox

The Router page also has a Use local Docker VM toggle. When enabled, Grok Bot runs its box host and execution daemon in an owned local container instead of connecting to the remote sandbox.

The container:

Docker Desktop, or another compatible local Docker daemon, must be running. Remote mode remains the default.

Requirements

Quick start

git clone <your-repository-url>
cd grok-bot-0.18-reconstructed
git lfs install
git lfs pull
npm ci
npm run bootstrap
npm run check
npm run package
open "dist/Grok Bot 0.18 Reconstructed.app"

npm run bootstrap first uses the Git LFS preservation copy of the pinned 0.18.0 DMG. If that archive is absent, it falls back to the original public URL; GROK_BOT_018_APP can also point to an existing application copy. Bootstrap verifies both the DMG and app.asar, caches the matching Electron runtime, and hydrates the ignored src/app/dist build input.

npm run package compiles the reconstructed runtimes, applies the narrow renderer/settings transform, creates the app bundle, assigns the reconstructed bundle identity, ad-hoc signs it, and verifies the result. Output is written to:

dist/Grok Bot 0.18 Reconstructed.app

Reconstructed packages disable the upstream updater at the packaging boundary and default upstream Sentry and telemetry emission off. Explicitly supplied environment configuration is still respected.

Architecture

polished shipped renderer
          │
          │ desktop preload / RPC
          ▼
     Electron main
          │
          ├── settings, secrets, auth and plugin lifecycle
          ├── remote box connector
          └── owned local Docker connector
                       │
                       ▼
              coordinator + host
                       │
              inference router
           ┌───────────┼───────────┐
        Cursor      Claude       Codex / OpenRouter
                       │
                 Grok Bot MCP tools

The main source areas are:

See docs/ARCHITECTURE.md for more detail.

Development commands

npm test                  # focused regression tests
npm run typecheck         # renderer TypeScript
npm run source:typecheck  # runtime TypeScript
npm run frontend:build    # build the readable renderer reconstruction
npm run package           # build, sign, and verify the macOS app
npm run verify            # verify an existing packaged app
npm run smoke             # bounded native smoke check
npm run publication:check # prove a fresh-history export is lossless

Generated directories including .cache, .build, dist, src/app/dist, recovered, recovery, and local probe roots are ignored.

Project status

The app launches and the core reconstructed flows are usable, including routed inference, connected plugins, and the local Docker sandbox. This is still an experimental reconstruction: it targets one pinned macOS/arm64 release, depends on external provider sessions, and does not promise compatibility with future Grok Bot versions.

For changes, read CONTRIBUTING.md. For the clean-history export procedure, see docs/PUBLISHING.md. Technical provenance and retained upstream boundaries are described in PROVENANCE.md and NOTICE.md.

grok-bot-0.18-reconstructed (b-nnett/grok-bot-0.18-reconstructed)

Searching Database…

3.5K ·GitHub
Grok-bot-0.18-reconstructed
archived
What is this?It's an unofficial, source-oriented reconstruction of the publicly shipped Grok Bot 0.18.0 macOS app, rebuilt into readable TypeScript sources and extended with an inference router, MCP tools, local usage tracking, and an optional local Docker sandbox.
Is this an official Grok Bot release or a reverse-engineered build?It is a hacking/research reconstruction, not Anysphere's original source or an official release; it hybridizes reconstructed runtime code from source/ with the original minified shipped renderer as the UI baseline.
How do I build and run the reconstructed app?Run 'npm run bootstrap' to download and SHA-256-verify the pinned 0.18.0 DMG (or point GROKBOT018APP at an existing copy), then run 'npm run package' to compile the runtimes, patch the renderer, and produce an ad-hoc signed app bundle.
What do I need installed before building it?You need macOS on Apple Silicon, Node.js 26.5.x, Xcode Command Line Tools, and Git LFS; Docker Desktop is only required if you want the local sandbox, and Claude Code/Codex router modes need those apps already logged in locally.
Is this safe to rely on long-term, or a one-off experiment?It's explicitly experimental: it targets only one pinned macOS/arm64 release, depends on external provider sessions staying valid, and makes no promise of working with future Grok Bot versions.
Can I build and run this on Windows too?No — building and running the reconstruction requires macOS on Apple Silicon; a Windows 0.18.0 installer is only preserved as a checksummed research artifact in research-archives/, not a supported build target.
Which AI providers can I route inference through?The Router supports Cursor (default, via your existing session), Claude Code and Codex (reusing local authenticated logins, no extra API key needed), and OpenRouter via a saved API key.
Is this project actively maintained?No — the repository is archived, so it's frozen as an experimental research snapshot rather than an actively developed project.
What does the local Docker sandbox replace?It swaps the remote execution box for a loopback-only local container running the same box host and execution daemon, mounting content-addressed artifacts read-only.
Why wasn't the whole UI rebuilt from scratch?The shipped app only contained minified, source-mapless production JS/CSS, so recreating the full original React frontend was out of scope; instead the team kept the checksum-verified shipped renderer and made a narrow patch for the new Router settings UI.
What are similar projects?claudecodeui, overmind, opensquilla, 1code, opencodex, deer-flow, claude-task-master, CanvasTTY
Which topics is it in?llm-router, openrouter, hacking, sandbox, reverse-engineering, electron, cursor, anthropic, codex, research, claude-code, mcp
Creator
b-nnett
Size
5.4 MB
Stars
3.5K
Updated
CommitAug 23
Age
1mo
Commits · 90 Days