The autonomous terminal coding agent, companion to NioXS & MicroLMs.
NioAI is a lightweight, blazing-fast terminal companion for NioXS. Engineered specifically to interface with our sovereign MicroLM (µLM) predator fleet (NioCuda, NioRay, NioViper, NioManta, NioNano, NioMicro, NioMask, NioMini), NioAI delivers sub-10ms DAG planning, electric keystroke code generation, and multi-file refactoring with zero telemetry and sub-20MB client memory.
⚡ Zero Manual Setup
NioXS and NioDB are pre-bundled. Running nio automatically ensures the companion gateway is live, starts NioCuda swarm conductor or local NioRay predator, and handles turn orchestration with zero extra steps.
🧠 MicroLM Swarm Intelligence
Default model is set to nioxs::nio-cuda (Tactical Swarm Conductor) and in-process nioxs::nio-ray (Keystroke Predator), orchestrating high-speed MicroLM specialists across your project within strictly bounded memory budgets (< 100MB RAM).
🌊 Fluid Typewriter Streaming
Real-time adaptive character-level typewriter stream rendering with zero ANSI escape flicker, smooth code-block frame borders, and sub-millisecond cadence.
🛡️ Transactional File Safety
Every file modification is tracked with atomic undo/redo backups. Path traversal attacks outside the project directory are mathematically rejected before execution.
🔌 Universal MCP & Plugins
Native Model Context Protocol (MCP) server & client support, dynamic custom plugins, and extensible tool chains without changing your workflow.
Quickstart
Get up and running in seconds using your package manager of choice.
Run directly without installation via npm/npx:
npx @nio-labs/nio-aiOr install globally to have the nio command available anywhere:
npm install -g @nio-labs/nio-ai
nio "Explain project architecture"Native standalone binary installation via shell script:
curl -fsSL https://raw.githubusercontent.com/nio-labs/nio/main/install.sh | shThis automatically downloads the pre-built native binary for Linux (x86_64, aarch64, musl, Termux) or macOS (Intel, Apple Silicon) and bundles the NioXS companion gateway.
Install on Windows via PowerShell:
irm https://raw.githubusercontent.com/nio-labs/nio/main/install.ps1 | iexBuild from source with Cargo:
cargo install --locked --git https://github.com/nio-labs/nio.gitNioXS Companion & MicroLM Fleet
NioAI and NioXS work as a unified pairing. NioAI is your interactive terminal agent and cockpit, while NioXS serves as the intelligent companion gateway orchestrating our sovereign MicroLM family.
Automatic Companion Gateway Management
When you start NioAI, it performs an instant health probe to http://127.0.0.1:7460. If the NioXS companion gateway is not running, NioAI automatically launches nioxs serve in the background. You never have to manually run or supervise background services.
| Component | Role | Default Status |
|---|---|---|
| NioAI | Terminal UI, multi-turn conversational agent, diff preview, tool dispatch | Interactive CLI |
| NioXS | Companion gateway, semantic caching, vector history, prompt handoff | Auto-spawned on port 7460 |
| NioCuda & MicroLM Fleet | Tactical Swarm Conductor (nioxs::nio-cuda) orchestrating local MicroLMs (< 160MB RAM) |
Default model selector |
| NioDB | Embedded local vector database and session persistent state | Bundled with NioXS (port 7432) |
Agent Modes
Tailor NioAI's permissions and tool accessibility to your workflow.
🔨 Build Mode
Full mutation capabilities. The agent can create files, apply diffs, execute diagnostics, and run test suites with interactive user confirmations.
📖 Ask Mode
Read-only investigation mode. Perfect for explaining complex codebases, reviewing pull requests, and auditing security without modifying files.
📋 Plan Mode
Decomposes complex architectural tasks into structured milestones before writing code. Produces actionable checklists.
Tools & MCP Protocol
Standardized, secure tool execution adhering to the Model Context Protocol.
# Inspect project capabilities and active MCP servers
nio mcp list
# Run command with specific MCP plugin enabled
nio plugins install <plugin-id>Personalization & Memory
NioAI adapts to your project coding style, preferred libraries, and workflows over time.
Persona Customization
Set persistent personas or behavioral directives:
nio persona set "Senior Rust Engineer specializing in async systems and high performance"Providers & Fallbacks
Fault-tolerant architecture guarantees continuous coding even during network dropouts or rate limits.
Default Fallback Chain
If NioAtom or the local gateway is temporarily unreachable, NioAI smoothly fails over along the deterministic chain:
nioxs::nio-cuda(Local Companion Gateway)kilo::openrouter/free(Global Free Router)kilo::cohere/north-mini-code:freekilo::stepfun/step-5-preview-freekilo::kilo-auto/free
Security & Safety
Engineered for enterprise trust and developer safety.
- Path Traversal Immunity: Canonical path resolution ensures tools can never read or write outside the current project root.
- Atomic Undo/Redo: Every patch is backed up in a project-scoped journal. Revert any turn instantly.
- Zero Remote Telemetry: Code, prompts, and session history remain strictly local on your machine.
CLI Commands
Quick reference for NioAI terminal subcommands.
| Command | Description |
|---|---|
nio [PROMPT] |
Launch interactive coding turn or prompt |
nio xs [ARGS] |
Directly invoke or manage the bundled NioXS companion gateway |
nio models |
List all available local and remote models |
nio provider |
Manage AI gateway providers and API credentials |
nio sessions |
View, resume, or export prior conversation sessions |
nio doctor |
Perform complete system health and compiler diagnostic check |
Looking for REPL & Interactive Mode Commands?
During an active coding session in the terminal, type : to access the interactive command palette. All 24 commands, shortcuts, and switches are detailed in the Interactive : Commands Guide →.
Frequently Asked Questions
Answers to common questions about setup, offline usage, providers, safety, and workflows.
Do I need to install NioXS or NioDB separately?
No. NioXS companion gateway and its embedded vector database are completely pre-bundled with NioAI. When you run nio or npx @nio-labs/nio-ai, NioAI automatically probes port 7460 and starts the background gateway seamlessly without any manual configuration.
What is NioAtom and why is it the default model?
NioCuda (nioxs::nio-cuda) is our purpose-built conductor model tuned specifically for autonomous multi-file refactoring, atomic diff application, compiler error recovery, and iterative project-level planning. It provides high precision with low latency and optimal token economy.
Can I use my own OpenAI, Anthropic, Gemini, or DeepSeek API keys?
Yes. You can configure providers interactively with :provider during a session, run nio provider add from your shell, or simply export standard environment variables such as OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, or OPENROUTER_API_KEY.
Can I run NioAI completely offline with local models?
Yes! NioAI seamlessly connects to local LLMs through Ollama, llama.cpp, or any OpenAI-compatible local server. Select your local model with :model or run nio --model ollama::qwen2.5-coder:32b. Vector memory and companion routing run 100% on your machine with zero cloud connectivity.
How does NioAI safeguard my codebase against unintended edits?
Every file modification is applied atomically with an automatic backup snapshot stored in your project journal. If any edit is unwanted, simply type :undo to roll it back instantly. Furthermore, strict path canonicalization mathematically prevents tools from reading or writing outside your repository root.
What is the difference between Ask, Plan, and Build modes?
Ask mode is completely read-only for answering questions, tracing architecture, and reviewing code without touching files. Plan mode analyzes requirements and decomposes tasks into structured implementation checklists. Build mode is the full autonomous agent that edits files, runs compilers, and validates tests. Switch modes anytime with :mode.
How do I customize project guidelines or assistant personas?
You can add a .niorules or AGENTS.md file in your repository root with team coding standards and conventions. You can also configure persistent personas using :persona menu or set one directly via nio persona set "Senior Rust Architect".
How does the prompt message queue work?
While NioAI is executing long tool runs or compiling code, you can continue typing new thoughts or follow-up instructions into the prompt. NioAI enqueues them into an internal message pipeline. You can manage or inspect pending items at any time with :queue, :queue pause, or :queue clear.
How do I review changes made during a coding turn?
Type :diff to view the active git diff across the repository. You can also press d or type :details immediately after a turn to toggle an expanded line-by-line diff view of the latest file edit.
Where are conversation sessions saved, and how do I resume them?
Session histories are automatically saved in .nio/sessions/ inside your project directory. You can browse and switch between past conversations interactively using :sessions or :history, or run nio sessions from your terminal.