A local-first terminal coding agent engineered for safety, recoverability, and cost transparency.
Direct official LLM endpoints, turn-by-turn file rollbacks, and crash-resilient session persistence.
- Granular Workspace Rollbacks: Automatically captures lightweight workspace snapshots before edits. Revert changes turn-by-turn (
/rollback turn) or to the session baseline (/rollback) without disturbing unrelated uncommitted local diffs. - Project Immunity Engine: Turns a
/rollbackor a! hard steerinto a persisted project-level constraint that is injected into later turns, so a rejected approach is not repeated. - Blast Radius Probe: After each edit, extracts the changed exported symbols using per-language patterns and searches the workspace for downstream references, reporting callers that may need updating.
- Speculative Worktree Racing (experimental): Runs candidate solutions in isolated Git worktrees and arbitrates between them by minimal diff, fastest pass, or highest score. The engine is exported as a library and is not yet reachable from the default agent loop.
- Crash-Resilient State Persistence: Conversations, task graphs, and execution states are incrementally journaled locally. Resume any interrupted session seamlessly via
xio resume. - Native Multi-Model Integration: Connects directly to official provider APIs including DeepSeek, Qwen (Aliyun DashScope), SiliconFlow, Zhipu AI (GLM), Anthropic Claude, OpenAI, and Google Gemini. No proxy servers required.
- Real-Time Token & Cost Metering: Turn-by-turn expenditure calculation based on actual token usage and versioned pricing tables (with config.toml override support), displayed in the status bar and web console.
- Dual Interface Modes: Full-featured terminal TUI with syntax highlighting, fuzzy search, and command palette, alongside a zero-dependency local Web console (
xio web) for visual timeline inspections. - Built-in Execution Guardrails: Intercepts destructive shell commands and unsafe file mutations, requiring explicit user authorization before execution.
- Ordered Browser Actions over MCP: MCP browser tools from one driver (e.g. Playwright) share a serial queue, so a whole
navigate → click → typesequence runs in one model round trip instead of racing in parallel. Setup, measured costs, and the extension-bridge login path: docs/browser-mcp.md. - Kernel-Backed Process Layer: supervised commands run on the embeddable
@xioflow/kernel— process intent recorded before spawn, stop confirmed by the driver before leases are released, per-stream truncation with spill artifacts, and crash-recovery adjudication of what a previous process left behind. Each prompt is a kernel run, direct-mode/rollbackuses kernel snapshots, and approvals are journaled (see ARCHITECTURE.md). SetXIOCODE_PROCESS_KERNEL=0to execute commands on the built-in supervisor instead. Processes a command leaves running are stopped when it ends; dev servers and watchers run as kernel-supervised background jobs (bashwithbackground: true, managed with thejobstool).
- Node.js: 22.13.0 or higher
- OS: macOS, Linux, Windows (WSL)
The kernel store uses node:sqlite, which is why Node.js 22.13+ is required. XIOCODE_PROCESS_KERNEL=0 switches command execution to the built-in supervisor; rollback, recovery and the journal stay on the kernel.
# Recommended: Automated installer
curl -fsSL https://raw.githubusercontent.com/Xio-Shark/xiocode/main/install.sh | bash
# Or install globally via npm
npm install -g @xioshark/xiocodePin a specific version:
export XIO_INSTALL_VERSION=1.6.0
curl -fsSL https://raw.githubusercontent.com/Xio-Shark/xiocode/main/install.sh | bashOnce installed, use either xio or xiocode.
Run inside any project directory:
xioOn first launch, run:
/connect
Select your provider and input your API key. Credentials are encrypted and stored locally under ~/.xiocode/—never transmitted to third-party relays.
Describe your requirements directly in the prompt:
> Implement a JWT authentication middleware with refresh token rotation and write comprehensive unit tests.
Workflow Tips:
- Interrupt & Steer: Press Enter or prefix with
!messageduring generation to adjust instructions mid-flight. - Context Pinning: Type
@to fuzzy-search and inject relevant files into context. - Help Sheet: Press
?on an empty line to view keybindings.
| Command | Scope | Description |
|---|---|---|
/rollback turn |
Single Turn | Reverts only files modified in the latest prompt, preserving existing local diffs |
/rollback |
Entire Session | Reverts all files modified throughout the session back to the initial baseline |
If a session terminates unexpectedly due to battery drain, terminal closure, or SIGINT:
xio resume # Restores the session with full context, task lists, and historyxio web # Launches the lightweight visual console at http://localhost:3080Inspect model interactions, tool call arguments, execution output, and timeline progression.
If 3080 is taken, xio web scans up to ten ports and reports the one it used; pass
--strict-port to fail instead, or --port 0 to let the OS choose.
The terminal UI and the web console share one copy table and one colour palette:
[ui]
language = "zh" # "zh" (default) or "en"; the web console re-reads it on reload
theme = "light" # groknight | light | claude | minimal | nord; written by /themeWithout a saved theme, xio asks the terminal for its background colour at start and picks light or the dark default; xio doctor shows what it detected. XIO_THEME overrides both. NO_COLOR turns colour off for both front ends; the boot splash is opt-in with XIO_SPLASH=1.
Approvals list their choices (allow once, allow for the session where it is safe, deny, deny and tell the model why); Esc always declines.
| Command | Description |
|---|---|
xio |
Launch the interactive terminal coding environment |
xio "task description" |
Execute a one-shot task and exit upon completion |
xio resume |
Resume the most recent active or interrupted session |
xio resume --prune |
Preview old sessions without a prompt; add --yes to delete, skipping worktrees and active sessions |
xio web |
Launch the local web timeline console (http://localhost:3080; the next free port if busy, --strict-port to refuse) |
xio doctor |
Diagnose environment, configuration, and API connectivity |
xio models |
Display provider/model ids, unit pricing, the endpoint each model is called on, configuration status, and models the provider no longer lists ([offline]; --refresh updates the saved lists) |
| Command | Description |
|---|---|
/connect |
Configure or switch provider API credentials |
/model |
Change active model on the fly |
/rollback turn |
Undo file changes made during the latest turn |
/rollback |
Undo all file changes made in the current session |
/immunity |
View or clear distilled negative project constraints (/immunity [clear]) |
/race |
Show experimental worktree racing engine status (not wired into the default loop) |
/compact |
Compress conversation history to optimize context window |
/theme |
Show or switch the colour theme (saved to [ui] theme) |
/clear |
Clear screen buffer and redraw active turn |
/help |
Display shortcuts and command manual |
- Local-First Architecture: API requests are dispatched directly from your machine to official provider endpoints. There are no proprietary relays or intermediary gateways.
- Zero Telemetry: We do not collect or transmit source code, prompts, or interaction telemetry. All states remain strictly in
~/.xiocode/. - Execution Guardrails: Unsafe file modifications and destructive shell commands (e.g., recursive removals) are paused for explicit human-in-the-loop approval.
Distributed under the MIT License. All code generated using XioCode belongs entirely to you.