opengrok README

The project's README from github.com/OnlyTerp/opengrok. As one markdown file: README.md.

open·grok — run any model in Grok Bot: pick a model, wire map applies, verified hop, survives updates. keys stay on your machine. now with the LiquidGlass Observatory.

setup license evidence verify deps platform

Pick a model per agent. Save. It talks native and survives Grok Bot updates.
Keys never leave your machine. Every wire claim in this repo is probe-verified, not vibed.

the LiquidGlass Observatory — swap any agent's model mid-chat, verified hops, live telemetry per bot, context guardian

✨ The LiquidGlass Observatory

The old picker was a dropdown. This is the deck it grew into — a frosted-glass mission-control panel that lives inside the Grok Bot window itself:

⚡ Quick start

What this repo is — and is not. opengrok is a config sidecar for an existing Grok Bot install: it writes model bindings, wire maps, and a health doctor next to your Grok Bot. It does not host or emulate Grok Bot, does not control your machine, and does not ship auth shims — your Grok Bot (desktop + optional cloud computer) stays exactly what it is; we only tell it which model to talk to. A "hop" here simply means any OpenAI-compatible base URL (the "OpenAI-compatible base URL" you'd paste in other tools).

Prerequisites: a working Grok Bot install (desktop app), Python 3.9+, Node 18+ (for the picker/maps), and API keys for any provider you bind.

git clone https://github.com/OnlyTerp/opengrok
cd opengrok
python setup.py

That's the whole install: it detects your Grok Bot install and live services, adopts existing bindings or asks 3 questions, writes its config, baselines your machine, and opens the picker. Then:

  1. pick a model for each agent in the dropdown
  2. test it live (one click, real request)
  3. save — done
python tools/doctor.py        # anytime: is everything still healthy?
python tools/qa.py            # repo self-check: leaks, refs, tests

🤖 What it gives each model

Dropping a foreign model into Grok Bot usually "works" and feels off — slower, dumber, token-hungry. That's harness mismatch: the model was RL-trained on its own harness's wire shape, and gets a generic prompt shape plus wrong reasoning knobs. opengrok fixes the wire:

Model family What goes wrong vanilla What opengrok does
Grok (xAI) effort knob is xhigh, not max; fast has no field literal token mapping, always-on reasoning documented
GLM (Zhipu) thinks by default — silence is expensive; max is real verified token table + true off-switch via thinking:disabled
Claude thinking is owned by the auth shim; body-painting it 400s shim-owned thinking, effort passes clean
Gemini "fast" was decorative — the knob is the slug, not a field fast lane rerouting, measured 1.5s → 0.9s first token
DeepSeek thinking lives in the model slug, not the body slug-owns-thinking mapping
local models context/recovery edges dedicated route, fail-closed

Every row of that table is backed by a capture in wire-captures/ (see glm-5.3-flash for the full ladder — bare request thinks by default, disabled really switches it off, max is a real token).

🧩 How it fits together

 Grok Bot agent
      │  modelId + parameters (thinking/effort/fast)
      ▼
 provider-maps ──► per-provider wire truth (verified, versioned, tested)
      │
      ▼
 upstream (xAI / Zhipu / Anthropic / Google / DeepSeek / local llama.cpp)

Two contracts, one story:

Cloud agents need one more step. Stock Grok Bot cloud hosts do not read model-bindings.json — a saved binding is ignored until you install the binding consumer into the host. tools/apply-box-patch.py does that (anchored, idempotent, backs up first), and tools/file-relay.py is the box-side file relay the picker pushes bindings to. See CLOUD-HOST for the full local → push → patch → bounce → verify flow.

🛡️ Update-proof by design

Grok Bot updates silently rewrite its bundle. Instead of hoping:

📚 The laws

Hard-won rules this repo encodes — each one earned by a real failure:

🧪 Testing (how we know it's true)

node tools/test-provider-maps.cjs       # 23/23 — Contract A
node tools/test-provider-maps-hop.cjs   #  6/6 — Contract B
python tools/qa.py                      # leak scan, ref integrity, suites

CI runs all three on every push and PR. The QA tool is itself negative-control-tested: plant a fake key or break a file and it fails loudly — a green that can't fail is decoration.

➕ Adding a provider

python tools/wire-probe.py --base https://api.example.com/v1 --model their-model --key-env THEIR_API_KEY

Run it, paste the verdict into a PR with the capture attached. CONTRIBUTING.md has the contract — no capture, no merge.

🧠 Codex Everywhere

Codex Everywhere is configured in OpenClaw as the OpenAI Responses API (openai-responses), while Grok Bot speaks Chat Completions. The repository ships a local, dependency-free bridge for this protocol boundary:

python3 tools/codex-everywhere-bridge.py \
  --api-key-env CE_API_KEY --port 18795

Provide CE_API_KEY through an OS-managed secret environment; never put it in model-bindings.json. Bind a CE model to the bridge with hopBaseUrl: "http://127.0.0.1:18795/v1" and the exact model ID, for example gpt-5.6-terra. The bridge converts /v1/chat/completions into /v1/responses, translates common tool, reasoning, and budget fields, and converts JSON/SSE Responses replies back to Chat Completions. See docs/CODEX-EVERYWHERE.md for the complete setup and the current compatibility boundary.

🎙️ Voice assistant (voice/)

A full local realtime voice assistant built on the same wire-truth philosophy:

Browser panel UI, zero native audio deps, all lanes localhost-only. Setup is a guided walkthrough (ElevenLabs key + Codex CLI login + Grok CLI login), with a doctor that tells you exactly what's missing:

node voice/doctor.js                      # pre-flight check
voice\scripts\start-voice.ps1             # start everything, open the panel

See voice/README.md · voice/SETUP.md.

🗺️ Status

not farming you, arming you.

opengrok (OnlyTerp/opengrok)

Searching Database…

487 ·GitHub
Opengrok
What is this?opengrok lets you run other LLMs (Claude, GLM, Qwen, Gemini, DeepSeek, local models) inside an existing Grok Bot desktop install, with evidence-based wire maps so each model gets the correct request shape instead of a generic prompt.
Is this its own app, or does it plug into Grok Bot?It is a config sidecar, not a standalone app: it writes model bindings and wire maps next to your existing Grok Bot install and tells it which model to talk to, without hosting or emulating Grok Bot itself.
How do I get it running?Run the installer: it detects your Grok Bot install and live services, adopts existing bindings or asks three setup questions, writes its config and a machine baseline, then opens the model picker so you can pick, test live, and save a model per agent.
What do I need before installing this?A working Grok Bot desktop install, Python 3.9+, Node 18+ for the picker and maps, and API keys for whichever model providers you plan to bind.
Does model binding work the same on cloud Grok Bot hosts?No — stock cloud Grok Bot hosts ignore saved bindings until you run the box-patch tool to install the binding consumer into the host; the local → push → patch → bounce → verify flow is required there.
Where do my provider API keys go?They stay local to your machine; opengrok never ships your keys off-box or into committed config.
What is the LiquidGlass Observatory?It's the in-app frosted-glass control panel inside Grok Bot that lets you swap a model mid-chat with no restart, see verified-hop proof per switch, watch per-bot telemetry (throughput, TTFT, token flow, cache hit rate), and track a context-window guardian bar across 28 bots.
Why can't I just point a model's API at Grok Bot directly?Each model family was RL-trained on its own harness's wire shape (reasoning-effort fields, thinking toggles, model-slug conventions). Dropping it in raw causes harness mismatch — it 'works' but runs slower and dumber. opengrok's provider maps fix the exact wire fields per model family, backed by captured probe evidence.
Does it include a voice assistant?Yes — the voice/ folder has a local, localhost-only realtime voice stack: streaming speech-to-text, an OpenAI realtime brain, and ElevenLabs text-to-speech with barge-in support, set up via a guided walkthrough.
How does it survive Grok Bot's silent updates?doctor.py baselines your machine on first setup and re-checks files, services, and caches after updates, reporting exactly what drifted; a --quiet mode stays silent when nothing changed, which is cron-friendly.
What are similar projects?casbin-gateway, aichat, router, openclaw-zero-token, opencodex, 9router, ccx, ThinkWatch-Lite
Which topics is it in?model-router, llm-gateway, voice-assistant, byok, grok, configuration, speech-recognition, tts, qwen, openai-compatible, local-llm, deepseek
Creator
OnlyTerp
Size
5.6 MB
Stars
487
Updated
CommitSep 22
Age
1mo
Commits · 90 Days