OpenGrok (grok)

English · 简体中文

A terminal-based AI coding agent — a full-screen TUI that understands your codebase, edits files, runs shell commands, searches the web, and manages long-running tasks.

---

About this fork. OpenGrok is an independent, rebranded fork of xAI's Grok Build, distributed under the Apache License 2.0. It is not affiliated with, sponsored by, or endorsed by SpaceXAI or xAI. "Grok" is a trademark of its respective owner; the Apache License does not grant rights to that mark. See NOTICE for attribution and the list of modifications made in this fork. The SOURCE_REV file records the upstream monorepo commit this tree is synced from.

Highlights

• Full-screen terminal UI with scrollback, prompt, and modals.
• Reads and edits your codebase; runs shell commands, search, and web fetch.
• Runs interactively, headlessly (grok -p "…" for scripting/CI), or embedded in editors via the Agent Client Protocol (ACP).
• Pluggable model backends, including custom / third-party OpenAI-compatible endpoints configured in ~/.grok/config.toml.

Building from source

Requirements:

• Rust — the toolchain is pinned by rust-toolchain.toml; rustup installs it automatically on first build.

• DotSlash — required so hermetic tools under bin/ (notably bin/protoc) can download and run. Install it and ensure dotslash is on your PATH before building:

  cargo install dotslash
  # or: prebuilt packages — https://dotslash-cli.com/docs/installation/
  /usr/bin/env dotslash --help   # sanity check

• protoc — proto codegen resolves bin/protoc via DotSlash, or falls back to a protoc on PATH / $PROTOC.

• macOS and Linux are supported build hosts; Windows builds are best-effort and not currently tested from this tree.

cargo run   -p xai-grok-pager-bin            # build + launch the TUI
cargo build -p xai-grok-pager-bin --release  # release binary: target/release/xai-grok-pager
cargo check -p xai-grok-pager-bin            # fast validation

The binary artifact is named xai-grok-pager; the launched command is grok. On first launch it opens your browser to authenticate. Custom / third-party OpenAI-compatible model endpoints can be configured in ~/.grok/config.toml (see the user guide under crates/codegen/xai-grok-pager/docs/user-guide/).

Configuring a model endpoint

By default grok signs in to your account on first launch. To route to any OpenAI-compatible endpoint instead — a self-hosted model, a corporate gateway, or a third-party relay — add a model block to ~/.grok/config.toml. Replace the placeholders below with your provider's values:

[model."my-model"]
model          = "MODEL_ID"                              # model name sent to the provider
base_url       = "https://YOUR_PROVIDER.example.com/v1"  # OpenAI-compatible base URL (placeholder)
name           = "My Model"                              # label shown in the model picker
env_key        = "MY_API_KEY"                            # env var holding the key — keeps secrets out of the file
api_backend    = "chat_completions"                      # "chat_completions" (default), "responses", or "messages"
context_window = 200000                                  # context size in tokens; drives auto-compaction

Keep the API key in an environment variable rather than in the file, then run:

export MY_API_KEY="YOUR_API_KEY_HERE"   # Windows PowerShell: setx MY_API_KEY "YOUR_API_KEY_HERE"
grok -m my-model                        # or switch inside the TUI with: /model my-model

The [model."…"] key is the local id you pass to -m / /model; model is the slug sent to the provider. For the full list of fields, see docs/user-guide/11-custom-models.md.

Repository layout

Path	Contents
crates/codegen/xai-grok-pager-bin	Composition-root package; builds the xai-grok-pager binary
crates/codegen/xai-grok-pager	The TUI: scrollback, prompt, modals, rendering
crates/codegen/xai-grok-shell	Agent runtime + leader/stdio/headless entry points
crates/codegen/xai-grok-tools	Tool implementations (terminal, file edit, search, ...)
crates/codegen/xai-grok-workspace	Host filesystem, VCS, execution, checkpoints
crates/codegen/...	The rest of the CLI crate closure (config, MCP, markdown, sandbox, ...)
crates/common/, crates/build/, prod/mc/	Small shared leaf crates pulled in by the closure
third_party/	Vendored upstream source (Mermaid diagram stack)

Important

The root Cargo.toml (workspace members, dependency versions, lints, profiles) is generated — treat it as read-only. Prefer editing per-crate Cargo.toml files.

Development

cargo check -p <crate>        # always target specific crates; full-workspace builds are slow
cargo test  -p xai-grok-config # per-crate tests
cargo clippy -p <crate>       # lint config: clippy.toml at the repo root
cargo fmt --all               # rustfmt.toml at the repo root

License

First-party code in this repository is licensed under the Apache License, Version 2.0 — see LICENSE and NOTICE.

Third-party and vendored code remains under its original licenses. See:

• THIRD-PARTY-NOTICES — crates.io / git dependencies, bundled UI themes, and in-tree source ports (including openai/codex and sst/opencode tool implementations).
• crates/codegen/xai-grok-tools/THIRD_PARTY_NOTICES.md — crate-local notice for the codex and opencode ports.
• third_party/NOTICE — vendored Mermaid-stack index.