ZacharyZhang-NY
6f31415ed6
The PRD's first acceptance gate now holds: grep -RinE '\bx\.ai\b|grok' crates/ --include='*.rs' → 0 matches (exempt: NOTICE and third-party license archives, README provenance, and the required 'Based on Grok Build Open Source' attribution, now sourced from version_attribution.txt). Wire-visible renames (both sides in this repo, changed in lockstep): - Auth method id 'grok.com' → 'kimi-code' (AuthMethodKind::KimiCode). - Every x.ai/* and _x.ai/* ACP ext method and meta key → kigi/* / _kigi/* (~200 names; grokShell → kigiShell). Session-file replay keeps a read-side alias for the legacy '_x.ai/session/update' method so existing updates.jsonl histories load; writes emit only the new name (both directions test-pinned). - Agent types grok-build* → kigi* with a documented legacy-prefix alias at resolution time so persisted sessions keep resolving. - ToolNamespace/BuiltinAgentName GrokBuild* → Kigi* (wire snake_case kigi/kigi_concise/kigi_hashline; schema regenerated); grok_build implementation dirs renamed to kigi*. - x-grok-* headers → x-kigi-*, __GROK_* sentinels → __KIGI_*, themes grokday/groknight → kigiday/kiginight (old persisted values fall back to the default theme), web_fetch allowlist xAI hosts → kimi.com + moonshot platforms, changelog CDN → this repo, grok-build changelog archives deleted. - BYOK default endpoint removed: [endpoints] api_base_url is now truly optional with NO default — consumers fail fast with the flag name when unset (no silent x.ai egress). Mock harnesses inject it explicitly. - System-prompt identity fixed: 'released by xAI' → 'an unofficial community CLI for Kimi' (template + regenerated encrypted form). Also repaired pre-existing grok-era test debt found by the sweep: the stale trace_classify default-model pin, the grok-pager UA label test, pty-harness stale-binary reuse and non-hermetic moonshot routing (a PTY test could previously reach the real api.moonshot.cn), and the outdated oauth fixture scope key. Gates: §9 grep 0; fmt clean; workspace check/clippy 0/0 (-D warnings); FULL cargo test --workspace: 234 suites, 21,961 passed, 0 failed; deny advisories ok.
256 lines
8.6 KiB
Markdown
256 lines
8.6 KiB
Markdown
# Getting Started
|
|
|
|
Kigi 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
|
|
kigi --version
|
|
```
|
|
|
|
Update to the latest version at any time:
|
|
|
|
```bash
|
|
kigi update
|
|
```
|
|
|
|
---
|
|
|
|
## First Launch
|
|
|
|
Start Kigi by running:
|
|
|
|
```bash
|
|
kigi
|
|
```
|
|
|
|
On first launch, Kigi opens your browser to authenticate with kigi.com. After you sign in, Kigi stores your credentials in `~/.kigi/auth.json`, where they persist across sessions. Kigi 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-..."
|
|
kigi
|
|
```
|
|
|
|
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, Kigi presents a full-screen TUI with two main areas:
|
|
|
|
- **Scrollback** -- the conversation history showing your prompts, Kigi'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. Kigi 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, Kigi 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: `kigi --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: `kigi -c`
|
|
|
|
### Scrollback
|
|
|
|
The scrollback is the main display area. It shows:
|
|
|
|
- **User prompts** -- your messages, rendered as sticky headers
|
|
- **Agent messages** -- Kigi's responses with full markdown rendering and syntax highlighting
|
|
- **Thinking blocks** -- Kigi'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
|
|
|
|
Kigi 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 kigi # 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
|
|
kigi "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 — `kigi -w "refactor module X"`
|
|
# would treat "refactor module X" as the worktree label, not the prompt.
|
|
kigi --worktree=feat "refactor module X"
|
|
|
|
# Base the worktree on a specific branch (e.g. main) instead of the current HEAD:
|
|
kigi -w --ref main "implement feature from main"
|
|
|
|
|
|
# Start in a specific project directory
|
|
kigi --cwd ~/projects/my-app
|
|
|
|
# Add project-specific rules
|
|
kigi --rules "Always use TypeScript. Prefer functional components."
|
|
|
|
# Auto-approve all tool executions
|
|
kigi --yolo
|
|
|
|
# Use a specific model
|
|
kigi -m kigi
|
|
|
|
# Resume a previous session
|
|
kigi --resume <session-id>
|
|
|
|
# Continue the most recent session
|
|
kigi -c
|
|
|
|
# Experimental scrollback-native render mode. Sticky: plain `kigi` reopens in
|
|
# the mode last chosen via --minimal/--fullscreen (or /minimal//fullscreen).
|
|
kigi --minimal
|
|
|
|
# Back to the standard fullscreen TUI (and make it sticky again)
|
|
kigi --fullscreen
|
|
|
|
# Headless mode (for scripts)
|
|
kigi -p "Explain this codebase"
|
|
```
|
|
|
|
---
|
|
|
|
## Headless Mode
|
|
|
|
Run Kigi non-interactively for scripting, CI/CD, and automation:
|
|
|
|
```bash
|
|
kigi -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
|
|
kigi -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. Kigi 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. Kigi 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 |
|