opengrok: a config sidecar that binds foreign models into an existing Grok Bot install
Run any model in Grok Bot — one-command setup, model picker UI, evidence-based provider wire maps, and an update-proof doctor. Not farming you, arming you.
At a glance
- What is it?
- opengrok writes model bindings and per-provider wire maps next to a Grok Bot desktop install so a bound agent can talk to xAI, Zhipu, Anthropic, Google, DeepSeek or a local llama.cpp endpoint. The interesting part is the wire-map layer and the doctor; the awkward part is that cloud-hosted agents need a patch applied to the host before a saved binding is read at all.
- Who is it for?
- Adopt opengrok if you already run Grok Bot on the desktop and want per-agent model choice without waiting on upstream support, and if you are willing to keep wire-captures and provider-maps in sync yourself when a provider changes its API.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 12 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem opengrok actually targets
Dropping a non-Grok model into Grok Bot usually appears to work. The README describes the result as slower, dumber and token-hungry, and attributes that to harness mismatch: the model was trained against its own provider's request shape and now receives a generic prompt shape plus reasoning knobs that do not mean what the caller thinks they mean. The README's table gives concrete examples. For Grok on xAI the effort knob is xhigh rather than max, and fast has no field at all. For GLM on Zhipu, thinking is on by default, so a bare request burns reasoning tokens unless you send thinking:disabled. For Gemini, the fast lane is selected by the model slug rather than by a body field. Each of those is a case where the request returns 200 and the knob does nothing, which the README calls out directly: a field that 200s and does nothing is worse than a 400. opengrok exists to encode the correct wire shape per provider and to prove that the shape is correct. The audience is narrow on purpose: someone with a working Grok Bot desktop install who wants to bind Claude, GLM, Qwen, Gemini, DeepSeek or a local model to a specific agent and have that binding behave the way the provider intended.
Two map contracts and where the hop proxy sits
The architecture diagram in the README is short and worth reading literally. A Grok Bot agent emits a modelId plus parameters covering thinking, effort and fast. That request passes through provider-maps, which the README describes as per-provider wire truth, verified, versioned and tested, and then reaches the upstream provider. There are two contracts. provider-maps.cjs handles direct body maps for client-side lanes. provider-maps-hop.cjs exposes applyHarnessControls() for hop lanes, and the README states that this is the one that ships on the box. A hop, in this project's vocabulary, is any OpenAI-compatible base URL, which is the same string you would paste into other tools as an OpenAI-compatible base URL. The distinction matters because the two contracts do different jobs: one rewrites the request body, the other applies harness controls on the hop path. The README also mentions a hop proxy that confirms each model switch end to end before the switch counts, with a Copy Proof action that produces a receipt. What the README does not spell out is the internal structure of applyHarnessControls() or how a hop is retried when the upstream rejects a control. Anyone evaluating this for a production binding should read provider-maps-hop.cjs directly rather than rely on the diagram.
Install, prerequisites and the commands that matter
The prerequisites are a working Grok Bot desktop install, Python 3.9 or newer, Node 18 or newer for the picker and maps, and API keys for whichever providers you bind. The install is three commands: git clone https://github.com/OnlyTerp/opengrok, cd opengrok, then python setup.py. According to the README, setup.py detects your Grok Bot install and live services, adopts existing bindings or asks three questions, writes its config, baselines your machine, and opens the picker. The picker is then a three-step loop: pick a model for each agent in the dropdown, test it live with one click against a real request, then save. Two maintenance commands are documented. python tools/doctor.py answers whether everything is still healthy, and python tools/qa.py runs a repo self-check for leaks, refs and tests. There are also node tools/test-provider-maps.cjs for Contract A and a second test file for the hop contract, though the README excerpt cuts off mid-filename. Note the shape of the install: it writes config next to an existing Grok Bot rather than replacing it, and the README is explicit that opengrok does not host or emulate Grok Bot, does not control your machine, and does not ship auth shims.
Cloud-hosted agents need a patch before bindings are read
This is the part most likely to surprise someone who reads only the quick start. Stock Grok Bot cloud hosts do not read model-bindings.json, so a saved binding is ignored until the binding consumer is installed into the host. tools/apply-box-patch.py does that, and the README describes it as anchored, idempotent and backing up first. tools/file-relay.py is the box-side file relay the picker pushes bindings to. The full local to push to patch to bounce to verify flow lives in docs/CLOUD-HOST.md. Two things follow. First, the one-command setup claim applies cleanly to the desktop path and only partially to the cloud path; the cloud path has an extra install step that touches the host. Second, idempotent and anchored are claims about the patch script, not about Grok Bot's bundle layout, so an upstream change that moves the anchor is exactly the kind of thing doctor.py is meant to surface. If your agents run on a cloud host and you are not comfortable applying a patch to that host, opengrok's binding UI will look broken for a reason that has nothing to do with the picker.
The doctor, drift detection and what update-proof means here
Grok Bot updates rewrite its bundle silently, which is the failure mode opengrok is built around. The README's approach is to stop hoping and start measuring. doctor.py baselines the machine during setup and then watches files, services and caches; after an update it reports exactly what moved. A --quiet flag keeps it silent when clean and complains only on drift, which the README notes is cron-friendly. Provider maps hot-reload, so fixing a route does not require a restart. Read that as a maintenance contract rather than a guarantee. The doctor tells you that something changed; it does not automatically repair the maps, and the README does not claim it does. The practical cost is that you own a periodic check. If you bind a provider and never run doctor.py, the first sign of a broken binding will be a wrong or failing reply in an agent, not a warning. The --quiet flag makes it cheap to run on a schedule, which is the intended shape of the workflow.
The evidence rule and the wire-captures directory
The README states a rule the repository encodes: no map lands without a wire capture, produced by tools/wire-probe.py. The captures live in wire-captures/, and the README points at wire-captures/glm-5.3-flash/ as the full ladder for one provider, showing that a bare request thinks by default, that disabled really switches it off, and that max is a real token. This is the most interesting design decision in the project. Most routers assert that a parameter works because the endpoint returned 200. opengrok asserts that a parameter works because a capture shows the behaviour changing, and the README treats a silent no-op as a documented outcome rather than something to hide. The limitation is scale. A capture-backed map is only as current as the capture, and providers change request shapes without notice. If Zhipu or Google alters a field, the map is wrong until someone re-probes and commits a new capture. That is a real ongoing cost, and it is the main reason to check whether a capture exists for your provider before binding it.
How this differs from a general-purpose OpenAI-compatible router
The obvious alternative is a standalone router such as LiteLLM, or a gateway like OpenRouter. The difference is where the translation lives. A general router exposes one OpenAI-compatible endpoint and translates every provider into that shape for any client. opengrok goes the other direction: it assumes the client is Grok Bot, keeps the agent's own modelId and parameter vocabulary intact, and translates per provider through maps that were probed against that provider's actual wire behaviour. That buys provider-specific correctness, such as the thinking:disabled off-switch for GLM or the slug-based fast lane for Gemini, at the cost of being tied to one host application. A router also typically handles key custody and multi-tenant access; opengrok's README says keys never leave your machine and that it ships no auth shims, so the trust boundary is your own box. Pick the router if you need one endpoint for many clients. Pick opengrok if the client is Grok Bot and the problem is that a bound model feels wrong rather than that it cannot connect.
Licence, maintenance and what to verify first
opengrok is MIT-licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a statement about the licence text, not legal advice; if you redistribute a modified copy, read LICENSE yourself and confirm how you are handling attribution. On maintenance, the material supports a few concrete points. There are no retrieved releases, so the project appears to be tracked from the main branch rather than tagged versions, which means an upgrade is a pull rather than a version bump. The maps are versioned in-repo and the README describes them as tested, with node tools/test-provider-maps.cjs covering Contract A. Your upgrade cost is therefore two things: re-running doctor.py after any Grok Bot update to see what moved, and re-running the map tests plus checking wire-captures/ after any provider API change. The first thing to verify before binding a provider is that a capture exists for it under wire-captures/. The second is whether your agents are desktop or cloud-hosted, because the cloud path needs tools/apply-box-patch.py and the desktop path does not.
Editorial conclusion
Adopt opengrok if you already run Grok Bot on the desktop and want per-agent model choice without waiting on upstream support, and if you are willing to keep wire-captures and provider-maps in sync yourself when a provider changes its API. Skip it if you do not already have Grok Bot installed, since it is explicitly a sidecar and not a host, and skip it if you need cloud-hosted agents to pick up bindings without touching the host, because that path requires tools/apply-box-patch.py. Before trusting it, run python tools/doctor.py after any Grok Bot update to see which files moved, and check wire-captures/ to confirm a capture exists for the provider you intend to bind.
Community notes