Grok Build for RisuAI RP

English · 한국어

Important

This is an unofficial, modified fork of xai-org/grok-build. It is not affiliated with or endorsed by xAI, SpaceXAI, or RisuAI.

This fork adapts Grok Build's headless runtime for local RisuAI role-play conversations. Its main change makes an explicitly empty tool allowlist (--tools=) mean exactly zero advertised tools instead of falling back to the coding-agent toolset.

• Upstream base: xai-org/grok-build@ed6d543643628663873c5de28298e022ed634238
• Upstream source revision: d6937fe255dce4133c3d000a50f9cb94de12f06f
• Grok Build version: 0.2.120 (alpha)
• Initial fork patch: 2e16da8dc5700d211f8da01c456783231108c2db
• License: Apache License 2.0, with upstream third-party notices preserved

Why this fork exists

The upstream headless parser treated both an omitted --tools argument and an explicitly empty --tools= argument as "no allowlist." Later fallback logic therefore restored the full coding toolset.

For an RP request, this advertised coding-tool schemas even when the bridge requested no tools. In the local E2E case used to develop this fork:

Measurement	Upstream behavior	This fork
Advertised tools	24	0
Input tokens	about 9,118	about 356–590

These token values are one local observation, not a universal benchmark. Character cards, conversation length, model behavior, and upstream changes all affect usage.

Fork changes

This fork:

• preserves the difference between an omitted tool allowlist and --tools=;
• applies the empty allowlist as a final session-level clamp;
• prevents coding tool schemas from being advertised in that mode;
• passes headless --no-memory into runtime configuration;
• replaces Unix-only protobuf output paths with portable temporary files;
• handles Windows drive letters in protoc dependency output; and
• fixes Windows/Rust 1.94 test-compilation issues exposed by the build.

Normal invocations that omit --tools retain upstream behavior. The interactive coding agent and its tools have not been removed from the source tree. RisuAI message conversion, the thin RP system prompt, and conversation to Grok-session mapping belong to a separate local bridge and are not bundled in this repository.

Modified files are identified by a one-line fork notice and include:

• crates/codegen/xai-grok-pager/src/headless/cli.rs
• crates/codegen/xai-grok-pager/src/headless.rs
• crates/codegen/xai-grok-pager-bin/src/main.rs
• crates/codegen/xai-grok-shell/src/agent/config.rs
• crates/codegen/xai-grok-agent/src/builder.rs
• crates/build/xai-proto-build/src/lib.rs
• Windows compatibility changes in the pager PTY harness and shell tests

Build on Windows

The fork was validated locally on Windows x64 with:

• Rust/Cargo 1.94.0 (pinned by rust-toolchain.toml)
• the MSVC C++ toolchain and Windows SDK
• DotSlash 0.5.7
• protobuf/protoc 35.1

Install the required helper tools:

cargo install dotslash --locked
winget install --exact --id Google.Protobuf

Open a new PowerShell window and locate protoc.exe:

$grokProtoc = Get-ChildItem `
  "$env:LOCALAPPDATA\Microsoft\WinGet\Packages\Google.Protobuf_*\bin\protoc.exe" |
  Select-Object -First 1

if (-not $grokProtoc) {
  throw "protoc.exe was not found."
}

$env:PROTOC = $grokProtoc.FullName
& $env:PROTOC --version

Build the release executable:

cargo fmt --all -- --check
cargo check --locked -p xai-grok-pager-bin
cargo build --locked -p xai-grok-pager-bin --release
.\target\release\xai-grok-pager.exe --version

Expected artifact:

target\release\xai-grok-pager.exe

The locally verified build reports:

grok 0.2.120 (ed6d543) [alpha]

Windows remains a best-effort upstream build host; this repository documents one verified configuration rather than promising official Windows support.

Authentication

This fork uses Grok Build's existing authentication flow. It does not include, replace, or bypass authentication.

.\target\release\xai-grok-pager.exe login

An eligible account and access to the selected model are still required. Authentication state remains in the current user's Grok configuration directory and must never be committed.

Tool-free headless example

$grokExe = Resolve-Path ".\target\release\xai-grok-pager.exe"
$grokSession = [guid]::NewGuid().ToString()

$commonArgs = @(
  "--no-auto-update",
  "--cwd", (Get-Location).Path,
  "--permission-mode", "dontAsk",
  "--tools=",
  "--no-plan",
  "--no-subagents",
  "--no-memory",
  "--disable-web-search",
  "--max-turns", "1",
  "--output-format", "json",
  "--system-prompt-override",
  "Produce one assistant reply. Follow the supplied character and conversation. Never use tools. Output only the reply.",
  "--verbatim",
  "--model", "grok-4.5",
  "--reasoning-effort", "low"
)

& $grokExe @commonArgs `
  --session-id $grokSession `
  --single "Remember the marker RPSESSION. Reply with only ACK."

& $grokExe @commonArgs `
  --resume $grokSession `
  --single "What marker did I ask you to remember? Reply with only the marker."

The first request creates a session with --session-id; later requests resume the same UUID with --resume. Adjust the model and reasoning effort to values available to your account. low is a reasoning-effort setting, not a non-thinking mode.

RisuAI bridge integration

The Node.js OpenAI-compatible bridge and RisuAI plugin are separate from this source tree. Point your local bridge at the compiled executable:

HOST=127.0.0.1
PORT=3030
BRIDGE_TOKEN=replace-with-at-least-24-random-characters
GROK_EXECUTABLE=C:\absolute\path\to\grok-build-risu\target\release\xai-grok-pager.exe
GROK_MODEL=grok-4.5
GROK_REASONING_EFFORT=low
TURN_TIMEOUT_MS=180000
SESSION_TTL_MS=518400000
BRIDGE_WORKDIR=./sandbox

518400000 milliseconds is 144 hours. BRIDGE_TOKEN is a local bridge secret, not an xAI API key.

The tested bridge launches this executable with the following policy:

--no-auto-update
--permission-mode dontAsk
--tools=
--no-plan
--no-subagents
--no-memory
--disable-web-search
--max-turns 1
--output-format json
--system-prompt-override <thin RP prompt>
--verbatim
--model <GROK_MODEL>
--reasoning-effort <GROK_REASONING_EFFORT>
--session-id <uuid>   # first request
--resume <uuid>       # later requests
--prompt-file <path>

A bridge can map one RisuAI conversation to one Grok Build session while that mapping remains available. An in-memory mapping is lost when the bridge restarts even if Grok session data still exists.

Validation

Run the focused regression suite:

cargo test --locked -p xai-proto-build --lib
cargo test --locked -p xai-grok-pager explicit_empty_tool_allowlist_means_no_tools --lib
cargo test --locked -p xai-grok-pager empty_denylist_remains_unset --lib
cargo test --locked -p xai-grok-shell main_cli_explicit_empty_tools_sets_deny_all_session_clamp --lib
cargo test --locked -p xai-grok-agent explicit_empty_session_allowlist_removes_all_tools --lib

Validation performed on 2026-08-05:

• six focused Rust regression tests passed;
• the release build completed successfully;
• direct CLI new-session and resume calls passed;
• the external local bridge test suite passed 13/13;
• temporary and production HTTP bridge E2E tests both passed; and
• the model request log reported tool_count=0 for new and resumed turns.

Observed input tokens in that smoke test:

Path	First request	Resumed request
Direct CLI	356	417
Local RisuAI bridge	495	590

Security and limitations

• --tools= disables all advertised agent tools, including file, shell, and web tools. It is not an operating-system sandbox.
• Keep the bridge bound to 127.0.0.1 unless you add a separately authenticated and encrypted network boundary.
• Use a long random bridge token and restrict CORS where applicable.
• Never commit .env, %USERPROFILE%\.grok, auth.json, session credentials, cookies, API keys, or bridge tokens.
• Do not expose an authenticated personal Grok session as a public or multi-user API.
• Character behavior still depends on the RisuAI card, conversation template, bridge transformation, and model behavior.
• Editing earlier messages or losing the bridge's session registry may create a new Grok session.
• Rebase updates must revalidate empty-allowlist semantics and headless option propagation.
• No prebuilt binaries or credentials are stored in this repository.

Upstream sync

Keep the official repository as upstream:

git remote add upstream https://github.com/xai-org/grok-build.git
git fetch upstream
git rebase upstream/main

Resolve any runtime changes carefully, then rerun the focused tests and E2E checks above.

License and modification notice

Upstream first-party code is licensed under the Apache License 2.0. Third-party components retain their original licenses; see THIRD-PARTY-NOTICES and the additional notice files in the source tree.

This fork changes the headless tool-allowlist and memory-option paths, Windows protobuf build handling, and related tests. The modified files carry a notice and the initial functional changes are recorded in commit 2e16da8.

Use of Grok Build and its service remains subject to the applicable terms, account eligibility, quotas, and policies.

Related projects

• xai-org/grok-build
• Grok Build documentation
• kwaroran/Risuai