M0: compilable skeleton — Kigi 0.1.0 fork surgery
Hard fork of xai-org/grok-build (Apache-2.0) re-targeted as Kigi, an
unofficial Kimi Code CLI community build.
Rename & identity
- 72 xai-*/xai-grok-* crates -> kigi-* (explicit: xai-grok-pager-bin ->
kigi-bin [binary `kigi`], xai-grok-pager -> kigi-tui; rest mechanical);
ptyctl, ptyctl-cli, third_party/ unchanged; proto package
xai.grok.tools.v1 -> kigi.tools.v1
- Config home ~/.kigi (KIGI_SHARE_DIR override), env prefix GROK_* ->
KIGI_*, `kigi --version` carries the unofficial-community-build notice
- clap identity, help text, startup banner, prompt templates rebranded
(templates re-encrypted)
Deletions (PRD removal list #5/#6/#7/#9/#10)
- voice input (xai-grok-voice) and all TUI wiring
- telemetry: Mixpanel client, external OTel stream, Sentry, OTLP layers,
trace/GCS/S3 upload queues (kigi-file-utils halved), workspace upload
module & dc_log, heap-profile uploader, auth-diagnostics uploader,
session-analytics halves of feedback; local zero-egress observability
preserved in new kigi-log crate (unified log, --debug firehose,
subsystem file logs, opt-in instrumentation)
- announcements (crate, remote-settings fields, TUI surfaces)
- plugin marketplace (crate, sources/browse/CTA/extensions-modal tab);
direct plugin install/uninstall/update via kigi-agent git_install kept
- relay/gateway/assets endpoints and features (agent relay, headless
relay transport, gateway bridge, LeaderEnvUrls); leader IPC socket now
~/.kigi/leader.sock + KIGI_LEADER_SOCKET, no ws-url derivation
- functional types rehomed instead of deleted: PermissionMode ->
kigi-config-types, McpInitStrategy -> kigi-mcp, PrCreationSource ->
session signals, TerminalDiagnostics -> kigi-pager-render, agent_id ->
shell util
Endpoints
- kigi-env rewritten: single production KigiEndpoints {coding_api_base_url
https://api.kimi.com/coding/v1 (KIGI_CODE_BASE_URL), oauth_host
https://auth.kimi.com (KIGI_OAUTH_HOST), update_base_url (GitHub
Releases API), upgrade_page_url}; GrokBuildEnvironment enum deleted
Toolchain & workspace hygiene
- Rust 1.97.0 pinned; edition 2024; full cargo update; git2 hoisted to
workspace at 0.21 (Option->Result API migration), quick-xml 0.41
- Root Cargo.toml hand-maintained (PRD §8.1): version 0.1.0 inherited by
all members, members sorted, unused deps pruned
- cargo-deny advisories gate (deny.toml with documented transitive
exceptions); CI workflow (check/clippy/fmt/deny/test, macOS+Linux)
- cross-crate test seams re-gated behind `test-support` cargo feature;
insta snapshot baselines renamed to the kigi_tui prefix
- clippy --workspace --all-targets: zero warnings; fmt clean
Fixes surfaced by the port
- updater probe/installer divergence (bin/kigi vs bin/grok symlink set)
- idle model-metadata refresh dead under KIGI_CODE_BASE_URL override
(new is_effective_coding_endpoint_url, loopback+override aware)
- macOS symlinked-TMPDIR fixture canonicalization (foreign_sessions,
fast-worktree); RSS measurement tests serialized via serial_test
Docs & legal (Apache §4)
- NOTICE added (upstream attribution + change statement); THIRD-PARTY
notices sustained; kigi-tools ported-code notices extended; README,
CONTRIBUTING, SECURITY, AGENTS.md rewritten
Out of scope for M0 (tracked): Kimi auth/inference (M1), search/fetch,
command parity, config import (M2), Computer Hub excision & final
brand-token sweep (M2), distribution & self-update rewrite (M3).
This commit is contained in:
@@ -0,0 +1,255 @@
|
||||
# Getting Started
|
||||
|
||||
Grok Build is a terminal-based AI coding assistant from SpaceXAI. It runs as a TUI (Terminal User Interface) that understands your codebase, executes shell commands, edits files, searches the web, and manages tasks.
|
||||
|
||||
You can use it interactively as a full-screen TUI, run it headlessly for scripting and CI/CD, or integrate it into editors via the Agent Client Protocol (ACP).
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
Install the latest stable release (macOS, Linux, or Windows via Git Bash):
|
||||
|
||||
```bash
|
||||
curl -fsSL https://x.ai/cli/install.sh | bash
|
||||
```
|
||||
|
||||
Install a specific version:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://x.ai/cli/install.sh | bash -s 0.1.42
|
||||
```
|
||||
|
||||
On **Windows (PowerShell)**, use the native PowerShell installer:
|
||||
|
||||
```powershell
|
||||
irm https://x.ai/cli/install.ps1 | iex
|
||||
```
|
||||
|
||||
Install a specific version:
|
||||
|
||||
```powershell
|
||||
$env:KIGI_VERSION="0.1.42"; irm https://x.ai/cli/install.ps1 | iex
|
||||
```
|
||||
|
||||
The PowerShell installer automatically adds `%USERPROFILE%\.kigi\bin` to your User PATH. Alternatively, install via [Git for Windows](https://gitforwindows.org/) (Git Bash) or MSYS2 using the bash script above. WSL users get the Linux binary automatically.
|
||||
|
||||
Verify the installation:
|
||||
|
||||
```bash
|
||||
grok --version
|
||||
```
|
||||
|
||||
Update to the latest version at any time:
|
||||
|
||||
```bash
|
||||
grok update
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## First Launch
|
||||
|
||||
Start Grok by running:
|
||||
|
||||
```bash
|
||||
grok
|
||||
```
|
||||
|
||||
On first launch, Grok opens your browser to authenticate with grok.com. After you sign in, Grok stores your credentials in `~/.kigi/auth.json`, where they persist across sessions. Grok refreshes your credentials automatically and prompts you to sign in again when they can no longer be renewed.
|
||||
|
||||
If you prefer API key authentication (e.g., for CI/CD or environments without a browser), set the `XAI_API_KEY` environment variable instead:
|
||||
|
||||
```bash
|
||||
export XAI_API_KEY="xai-..."
|
||||
grok
|
||||
```
|
||||
|
||||
See [Authentication](02-authentication.md) for the full set of auth options including OIDC, external auth providers, and device code flow.
|
||||
|
||||
---
|
||||
|
||||
## Basic Interaction
|
||||
|
||||
Once authenticated, Grok presents a full-screen TUI with two main areas:
|
||||
|
||||
- **Scrollback** -- the conversation history showing your prompts, Grok's responses, tool calls, file edits, and more.
|
||||
- **Prompt** -- the input area at the bottom where you type messages.
|
||||
|
||||
Type a message and press `Enter` to send it. Grok reads files, runs commands, and edits code as needed. Each tool run streams into the scrollback in real time.
|
||||
|
||||
Press `Tab` to move focus between the prompt and the scrollback. While a turn is running, `Ctrl+C` cancels it (or clears a non-empty draft first); `Esc` is a no-op mid-turn. Idle, press `Esc` twice within 800ms to clear a non-empty prompt, or (with an empty prompt and conversation messages) to open rewind — see [Keyboard Shortcuts](03-keyboard-shortcuts.md#escape). With the scrollback focused, use the arrow keys to select entries and to collapse or expand them. To navigate with `j`/`k` and fold with `h`/`l` instead, enable Vim mode.
|
||||
|
||||
### File References
|
||||
|
||||
Use `@` in your prompt to attach files:
|
||||
|
||||
```
|
||||
@src/main.rs # Attach a file
|
||||
@src/main.rs:10-50 # Attach lines 10-50
|
||||
@src/ # Browse a directory
|
||||
```
|
||||
|
||||
The `@` operator opens a fuzzy file picker. By default it respects `.gitignore` and hides dotfiles. Prefix with `!` to search hidden files:
|
||||
|
||||
```
|
||||
@!.github # Search hidden files
|
||||
@!.env # Attach a .env file
|
||||
```
|
||||
|
||||
### Permissions
|
||||
|
||||
By default, Grok asks for permission before executing shell commands or editing files. You can approve individually or toggle always-approve mode:
|
||||
|
||||
- Press `Ctrl+O` to toggle always-approve mode
|
||||
- Use the `--yolo` flag at launch: `grok --yolo`
|
||||
- Type `/always-approve` in the prompt to toggle the mode
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Sessions
|
||||
|
||||
Every conversation is a **session**. Sessions are automatically saved to `~/.kigi/sessions/` and can be resumed later. Each session tracks the full conversation history, tool calls, file edits, and task state.
|
||||
|
||||
- Start a new session: `Ctrl+N` or `/new`
|
||||
- Resume a previous session: `/resume` in the TUI, or `--resume <ID>` from the CLI
|
||||
- Continue the most recent session: `grok -c`
|
||||
|
||||
### Scrollback
|
||||
|
||||
The scrollback is the main display area. It shows:
|
||||
|
||||
- **User prompts** -- your messages, rendered as sticky headers
|
||||
- **Agent messages** -- Grok's responses with full markdown rendering and syntax highlighting
|
||||
- **Thinking blocks** -- Grok's reasoning process (collapsible)
|
||||
- **Tool calls** -- file edits (with inline diffs), command executions, search results, and more
|
||||
- **Task lists** -- TODO items tracking progress
|
||||
|
||||
Collapse or expand the selected entry with the `Left`/`Right` arrow keys (or `h`/`l` and `e` in Vim mode). In Vim mode, press `y` to copy its content and `Y` to copy its metadata (for example, the command that ran). Press `Enter` to open it in the fullscreen viewer (in any mode).
|
||||
|
||||
### Tools
|
||||
|
||||
Grok has built-in tools for:
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `read_file` / `search_replace` | Read and edit files with line-precise changes |
|
||||
| `grep` | Regex search across your codebase (powered by ripgrep) |
|
||||
| `list_dir` | List directory contents |
|
||||
| `run_terminal_command` | Execute shell commands |
|
||||
| `web_search` / `web_fetch` | Search the web and fetch URLs |
|
||||
| `todo_write` | Create and manage task lists |
|
||||
| `spawn_subagent` | Spawn parallel subagent sessions |
|
||||
| `memory_search` | Search cross-session memory |
|
||||
|
||||
Tools can be extended with [MCP servers](05-configuration.md#mcp-servers) for integrations like GitHub, databases, and more.
|
||||
|
||||
### Slash Commands
|
||||
|
||||
Type `/` in the prompt to access commands. These provide quick actions without writing a full prompt:
|
||||
|
||||
```
|
||||
/model grok-build # Switch model
|
||||
/compact # Compress conversation history
|
||||
/always-approve # Toggle always-approve mode
|
||||
/new # Start a new session
|
||||
```
|
||||
|
||||
See [Slash Commands](04-slash-commands.md) for the complete reference.
|
||||
|
||||
---
|
||||
|
||||
## Common Launch Options
|
||||
|
||||
```bash
|
||||
# Launch the interactive TUI and submit an initial prompt as the first turn
|
||||
grok "fix the failing auth test and run it"
|
||||
|
||||
# Initial prompt in a new git worktree. Use --worktree=<name> (with `=`) so the
|
||||
# prompt isn't swallowed as the worktree name — `grok -w "refactor module X"`
|
||||
# would treat "refactor module X" as the worktree label, not the prompt.
|
||||
grok --worktree=feat "refactor module X"
|
||||
|
||||
# Base the worktree on a specific branch (e.g. main) instead of the current HEAD:
|
||||
grok -w --ref main "implement feature from main"
|
||||
|
||||
|
||||
# Start in a specific project directory
|
||||
grok --cwd ~/projects/my-app
|
||||
|
||||
# Add project-specific rules
|
||||
grok --rules "Always use TypeScript. Prefer functional components."
|
||||
|
||||
# Auto-approve all tool executions
|
||||
grok --yolo
|
||||
|
||||
# Use a specific model
|
||||
grok -m grok-build
|
||||
|
||||
# Resume a previous session
|
||||
grok --resume <session-id>
|
||||
|
||||
# Continue the most recent session
|
||||
grok -c
|
||||
|
||||
# Experimental scrollback-native render mode. Sticky: plain `grok` reopens in
|
||||
# the mode last chosen via --minimal/--fullscreen (or /minimal//fullscreen).
|
||||
grok --minimal
|
||||
|
||||
# Back to the standard fullscreen TUI (and make it sticky again)
|
||||
grok --fullscreen
|
||||
|
||||
# Headless mode (for scripts)
|
||||
grok -p "Explain this codebase"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Headless Mode
|
||||
|
||||
Run Grok non-interactively for scripting, CI/CD, and automation:
|
||||
|
||||
```bash
|
||||
grok -p "Your prompt here"
|
||||
```
|
||||
|
||||
Output formats:
|
||||
|
||||
| Format | Flag | Description |
|
||||
|--------|------|-------------|
|
||||
| `plain` | (default) | Human-readable text |
|
||||
| `json` | `--output-format json` | Single JSON object with `text`, `stopReason`, `sessionId`, and `requestId` |
|
||||
| `streaming-json` | `--output-format streaming-json` | NDJSON event stream for real-time processing |
|
||||
|
||||
Example CI/CD usage:
|
||||
|
||||
```bash
|
||||
grok -p "Review changes for bugs" --output-format json --yolo | jq -r '.text'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Rules (AGENTS.md)
|
||||
|
||||
Add per-project instructions by creating an `AGENTS.md` file in your repository. Grok reads these files and injects their contents as a project-instructions message at the start of the conversation:
|
||||
|
||||
```
|
||||
~/.kigi/AGENTS.md # Global rules (apply to all projects)
|
||||
<repo-root>/AGENTS.md # Repository-level rules
|
||||
<cwd>/AGENTS.md # Directory-level rules (highest priority)
|
||||
```
|
||||
|
||||
Deeper files take precedence. Grok also reads `CLAUDE.md` files for compatibility.
|
||||
|
||||
---
|
||||
|
||||
## Where to Go Next
|
||||
|
||||
| Document | What You Will Learn |
|
||||
|----------|-------------------|
|
||||
| [Authentication](02-authentication.md) | Browser login, API keys, OIDC, external auth, device code flow |
|
||||
| [Keyboard Shortcuts](03-keyboard-shortcuts.md) | Complete reference for all key bindings |
|
||||
| [Slash Commands](04-slash-commands.md) | All available `/` commands |
|
||||
| [Configuration](05-configuration.md) | config.toml, pager.toml, environment variables |
|
||||
Reference in New Issue
Block a user