NioAI

NioAI is open source software released under the MIT License. Contributions, issues, and usage questions are welcome.

NioAI is a lightweight, open source AI coding agent for the terminal. The executable is nio. It talks to configurable OpenAI-compatible model endpoints. Provider access, model availability, and free quotas depend on the provider and may change.

An older, separate NIO platform also provides a nio command. If both are installed, use the full executable path or adjust PATH.

Current release: v0.3.3.

Use nio --version, nio -v, or nio --v to print the installed version.

What’s new in v0.3.3

• Voice input & audio LLM support: Record microphone audio and query LLMs with :voice and nio voice, featuring native macOS AVFoundation recording, live recording timer, Whisper speech-to-text, and multimodal audio input.
• Dedicated visible search input in menus: Added visible search input box with live filtering and navigation to :plugins and picker menus.
• Provider failover & recovery: Prompt to switch providers or retry when connection drops or providers become unavailable.
• Snippets & NioDE daemon: Manage reusable code snippets with :snippets and background IDE language services with :ide.

What’s new in v0.3.2

• Wrap long fenced code lines inside their frame, accounting for response indentation and wide characters. Wrapped lines retain the frame prefix and complete code text.

What’s new in v0.3.1

• Delay the assistant label until visible text arrives, removing blank replies between tool calls and keeping working status visible while Markdown tables are buffered.

What’s new in v0.3.0

• Find files by glob and search code with literal or regex queries, numbered context, and pagination.
• Read supplied web URLs with web_fetch, without a search service or search API key.
• Ask focused clarification questions and manage approved terminal commands with incremental output.
• Render italics and streamed tables, including bold and italic table cells.
• Allow URL reading and questions in Studio and Canvas while project tools are disabled.

Features

Requirements

• Rust toolchain to build from source
• Any OpenAI-compatible provider you configure; Kilo is available by default

Build

cargo build --release

The executable is at target/release/nio.

Install

Zero-install via npx

If you have Node.js available, launch NioAI instantly with zero manual installation:

npx @nio-labs/nio-ai

Run one-shot prompts or flags directly:

npx @nio-labs/nio-ai run "Explain this project"
npx @nio-labs/nio-ai models --format json

The npm launcher caches binaries by package version and platform, verifies checksums before extraction, and checks the executable version before using it. Downloads require HTTPS and have a two-minute deadline. It does not automatically use another nio from PATH; set NIO_BIN to explicitly use your own executable.

To install globally via npm:

npm install -g @nio-labs/nio-ai
nio

Shell installer (Linux, macOS, Termux)

Install the pre-built native binary via curl:

curl -fsSL https://raw.githubusercontent.com/nio-labs/nio/main/install.sh | bash

Prefer inspecting the script before piping to shell?

curl -fsSL https://raw.githubusercontent.com/nio-labs/nio/main/install.sh -o install.sh
less install.sh
bash install.sh

Custom installation options:

# Pin a specific version
curl -fsSL https://raw.githubusercontent.com/nio-labs/nio/main/install.sh | NIO_VERSION=v0.3.3 bash

# Custom install path (defaults to ~/.local/bin)
curl -fsSL https://raw.githubusercontent.com/nio-labs/nio/main/install.sh | NIO_INSTALL_DIR="$HOME/.local/bin" bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/nio-labs/nio/main/install.ps1 | iex

Both native installers require a valid checksum before extraction and refuse to replace an unrelated nio executable. Pinned installations also verify the downloaded executable version.

See INSTALL_PLAN.md for supported native platform targets and verification plans.

Quick start

Start the agent. On first launch, Nio fetches models, shows free models first, and saves your choice:

nio

Override the model for one run:

nio run -m kilo::kilo-auto/free "Explain this project"

Screenshots

Inline CLI showing a project analysis in progress:

Full-screen TUI with the command palette open:

Queue messages while working

In the inline CLI, a persistent queue> input stays available during a response. The agent continues working while you type. Enter queues the message; unfinished drafts stay available when the response completes. Messages run in order after the current task finishes. Queued messages do not enter model context until they run.

• F2 or :queue — open the queue panel; arrows select, Enter/e edits, Delete/d removes, and p pauses/resumes
• :queue edit 2 New message — replace a pending message
• :queue remove 2 / :queue clear — remove pending work
• :queue pause / :queue resume — control automatic processing
• :stop — stop the response and preserve pending messages

Queue controls work while a response is running. Other commands entered in the inline queue prompt run after the response; the TUI also supports skill commands during a response. Errors and interruptions pause the queue. Pending messages are kept in memory for the running session.

GitHub skills

Install a skill folder containing SKILL.md from a GitHub repository. Git is required. Local folders are not accepted as installation sources.

nio --skills
nio --skills add https://github.com/your-org/your-repo path/to/skill
nio skills add https://github.com/your-org/your-repo/tree/main/path/to/skill
nio --skills disable skill-name
nio --skills enable skill-name
nio --skills remove skill-name

nio --skills defaults to listing installed skills; nio skills remains available as an alias. The same operations are available through :skills or /skills in interactive mode. Installed packages and their enable/disable settings are stored beside the Nio configuration. New installations are enabled by default. The model receives a catalog of enabled skills and can read relevant instructions and supporting text files through read_skill_file. Changes affect subsequent requests; skill instructions retain the current mode and approval restrictions.

Optional plugins

Plugins add executable file readers without bundling their dependencies into nio. PDF is the first available plugin; other readers can use the same package interface.

nio --plugins                         # installed and available plugins
nio plugins install pdf               # PDF text extraction, no OCR models
nio --plugins install pdf --languages eng,khm
nio --plugins install pdf --languages all
nio --plugins languages pdf            # language codes and download sizes
nio --plugins disable pdf
nio --plugins enable pdf
nio --plugins remove pdf
nio --plugins list --format json

nio --plugins opens a provider-style selection menu in an interactive terminal; nio plugins is an alias. Choose the PDF plugin to install, enable, disable, or remove it. For OCR, mark the language packs you need and select Install PDF plugin with selected languages (or Install selected OCR languages if PDF is already installed). Install all languages remains an explicit option. The TUI language list also supports text search. nio --plugins list prints a plain list; JSON and noninteractive invocations remain scriptable. :plugins and /plugins also work in the interactive prompt and TUI. Packages, enabled settings, and OCR models are stored beside the Nio configuration. Removing a plugin also removes its downloaded models. Installations are serialized and staged before registration. Reinstalling pdf adds missing languages and enables the plugin; it does not remove existing models.

The PDF plugin is a separate nio-pdf executable. The installer uses a worker alongside nio for local builds, or downloads the worker for the current platform and nio version from the official release and verifies its SHA-256 checksum. Released base nio archives do not contain the PDF worker. Plugin download installation requires a release publishing the matching worker asset; until then, build both binaries locally:

cargo build --release --locked --bin nio
cargo build --release --locked --features pdf-plugin --bin nio-pdf
./target/release/nio --plugins install pdf

PDF text extraction needs no other program. OCR is optional: install language models and provide tesseract and Poppler's pdftoppm on PATH. For example, macOS uses brew install tesseract poppler, and Debian/Ubuntu uses apt install tesseract-ocr poppler-utils; Windows users need compatible Tesseract and Poppler installations on PATH. Nio does not automatically run a system package manager. Models may run an approved setup command in Build mode when the user requests it.

Language packs come from a pinned official tessdata_fast revision and are verified against its Git blob checksums. Selected languages download only their models. all installs 126 models (about 339 MiB), including orientation/math models; it does not use all of them simultaneously for recognition. read_file accepts ocr_languages, for example ["eng", "khm"], to choose up to eight installed recognition languages. Without a selection, OCR uses English if installed, otherwise the first installed recognition language. osd is orientation data and cannot be selected as a recognition language.

The PDF reader extracts each page's existing text layer and uses OCR for pages with no extractable text. It keeps page labels and marks OCR results. Inputs are capped at 20 MiB, extracted text at 512 KiB, PDFs at 1,000 pages, and OCR at 50 pages per document. Each render/OCR process has a 60-second timeout; plugin reads have a 300-second total timeout. Split larger scans into smaller documents. Embedded images on a page that already has text are not separately OCR'd, and OCR can misread text.

Models can inspect list_plugins in every mode. install_plugin is available in Ask, Plan, and Build so file analysis can install a needed reader or OCR language packs without a mode switch. Ask and Plan always require explicit installation approval, even if automatic approval is enabled; noninteractive Ask and Plan runs deny installation. manage_plugin (enable/disable/remove) still requires Build mode and approval. Installation approval names the plugin, OCR selection, and estimated model download size. When a PDF is attached in an interactive session and the reader is missing, nio asks for installation approval before sending the document to the model. A filename containing “scan” suggests English OCR for this prompt. If installation is declined or OCR support is missing, the model sees the read error and can explain the next step. Reading never installs plugins or downloads languages implicitly. --no-tools disables model plugin management too.

The current plugin catalog contains the PDF reader. The plugin system can support other readers in the future. Installed plugin code runs locally with host access, and plugin output is bounded and treated as untrusted data.

Full-screen interface

nio --tui
nio --tui --session SESSION_ID

The optional TUI uses a theme background, a scrollable conversation, and a persistent input area. Enter sends a message when idle and queues it while working. Shift+Enter or Alt+Enter inserts a newline when supported by the terminal. Long pastes use compact markers. Use the mouse wheel/trackpad or Page Up/Down to scroll, and click the input to position the cursor.

: and / open the command palette. :setting, :mode, :model, :reasoning, and :theme open selection panels. :sessions opens recent saved conversations; :details opens the latest diff. Approval prompts use Y/N and D for details. Ctrl+C stops the current work and pauses pending messages. :quit saves the session and restores the terminal.

In the model picker, press Ctrl+P to filter by provider, or choose All providers to reset the filter. Text search continues to work within the selected provider.

The model picker filters by model name, selector, or provider as you type; Backspace edits the search and Ctrl+U clears it. Arrow navigation updates only changed screen rows.

The theme panel previews each highlighted theme immediately. Enter saves it; Esc restores the saved theme. Available palettes include Tokyo Night and the muted light options Light, Paper, and Cloud.

TUI settings also accept explicit values, such as :mode build, :theme ocean or :theme light, and :proxy off. :provider displays saved providers; configure provider credentials with nio provider in the inline CLI.

Configure and run

Nio asks whether to trust the current project folder before enabling file access and tools. Trusted folders are remembered. Untrusted non-interactive projects stay locked unless you pass --trust-project. In an interactive terminal, Nio still prompts on first access.

Key commands:

• :clear — clear the conversation
• :diff — review git changes
• :undo — revert the last agent file change, including changes from earlier runs in this project
• :quit — exit
• :provider — add or update a provider
• :mode — choose Ask, Plan, or Build
• :models — browse the model catalog
• :settings — inspect and edit saved settings

Presets include OpenRouter, OrcaRouter, AIHubMix, Groq, Cerebras, Gemini, DeepSeek, Together AI, Fireworks, Mistral, SiliconFlow, Anthropic Claude, and OpenAI Codex.

File tools stay inside the current directory. Auto-discovery skips generated folders, secret filenames, and .gitignore paths. Text reads and writes are capped at 512 KiB; supported document inputs may be up to 20 MiB, with at most 512 KiB of extracted text. Search reads at most 16 MiB and returns at most 50 entries. .gitignore parsing is bounded to 256 KiB.

Undo history is stored privately beside the configuration, in undo/, and is shared by sessions for the same canonical project folder. It keeps up to 32 file edits within an 8 MiB journal budget, dropping the oldest entries when needed. Undo checks that the file still matches Nio's edit and refuses to overwrite later changes; failed undo attempts keep their recovery entry. Shell-command changes are not covered by this history.

Agent tools

Nio offers bounded tools with small results:

• list_plugins, install_plugin, manage_plugin: inspect optional file readers, install plugins/add OCR languages, and enable/disable/remove plugins. Models can install readers and OCR languages in every mode with approval; enable/disable/remove requires Build.
• find_files: discover project files with path/glob filters and pagination. path defaults to . and stays within the active project; use nio --dir /path/to/project to work in another folder, or :path to inspect the current folder.
• search_code: literal or regex search with numbered lines, short context, and pagination.
• web_fetch: read an HTTP(S) page as text using the configured proxy, with a 20-second request timeout. HTML scripts/styles are removed; JavaScript execution, browser clicks, and forms are unsupported. Responses are capped at 1 MiB, excerpts at 8,000 characters, with next_offset for more.
• ask_user: ask one clarification question with up to three choices. In the regular prompt and full-screen TUI, select an answer with the arrow keys or type your own; nio continues the same turn. Noninteractive runs show the question for your next reply.
• terminal_start, terminal_read, terminal_cancel: start an approved command, read incremental output, and stop it. Starting/stopping commands requires Build mode; sessions live within one Nio process and stop when it exits. At most four commands run concurrently, with a one-hour maximum timeout and a 64 KiB output tail.

Ask and Plan allow research and project reads, while Build allows approved edits and commands. --no-project-tools allows web research, questions, and skill reading without project file or shell access. --no-tools disables every agent tool. web_fetch sends requests to the supplied website URL.

When implementation requires Build mode, Nio can offer a Yes/No switch with request_build_mode. Reply yes or 1 to switch to Build and continue the task, or no to keep the current mode. The switch saves Build as your default; file and command approval settings still apply.

Sessions and output

Terminal responses render headings, bold (**text**), italics (*text*), lists, inline/fenced code, and streamed Markdown tables. JSON output preserves the original Markdown for host applications.

Persist and resume conversations with -s:

nio run -s my-chat -m kilo::kilo-auto/free "Check my project"
nio run -s my-chat -m kilo::kilo-auto/free "Now explain the config files"

Emit machine-readable events with --format json:

nio run --format json ...

See STREAM.md for event shapes and PROTOCOL.md for CLI options, trust behavior, and host integration.

Settings and config

Common settings:

nio config list
nio config get model
nio config set theme Monokai

Toggle automatic approval for a single run with --auto. Set reasoning effort with :reasoning or --reasoning. Toggle mouse input with :mouse. Route traffic through a proxy with :proxy or NIO_PROXY.

Privacy

NioAI includes no telemetry, analytics, tracking, or background reporting. Network requests only go to features you use: model discovery, provider checks, responses, requested web pages, and requested skill/plugin/language downloads. Prompts, conversation context, project files, tool results, and approved command output can be sent to the model endpoint. Review your provider's terms before sending sensitive information. Credentials and sessions are stored locally; on Unix they are restricted to your user account. Avoid putting API keys directly in shell history.

NioDE integration

NioAI is available as the nio agent through NioDE's direct subprocess route. Install a current native nio executable on the server's PATH; Nio does not require npm or a persistent agent server. Automatic installation awaits published, verified native release artifacts.

The Chat UI requests project access before enabling Nio tools. Build consent also grants file edits and shell execution for that conversation/project. Ask and Plan allow reads and approved plugin/language installation; project editing and shell execution require Build. Installed third-party plugin executables remain trusted host code. Studio and Canvas use --mode ask --no-project-tools with Nio 0.3.0 or later; it receives generated text and owns its file writes.

For another host, the explicit interface is:

nio models --format json
nio run -m kilo::kilo-auto/free --format json --mode ask --reasoning low \
  --trust-project --dir /path/to/project -s project-chat -- "Explain this project"

--trust-project grants project reads for this invocation. --no-tools disables all project discovery and tools, even for remembered trusted folders. --auto grants writes and shell commands for a single invocation; noninteractive runs ignore saved automatic approval preferences. Approved commands have the current user's host access; the project directory is their starting directory, not a shell sandbox. NIO_API_KEY overrides credentials for the selected chat provider and is not broadcast to model catalogs. Catalogs use provider-specific saved or environment credentials. --reasoning accepts low, medium, high, or default. --file PATH attaches a supported document, UTF-8/UTF-16 text file, or a PNG, JPEG, GIF, or WebP image. In prompts, use @path or @{path with spaces} to attach an existing file; in the regular interactive prompt and --tui, an existing absolute path pasted or dropped into the prompt is also attached automatically. read_file can read a specific absolute local path when you ask about it, including image files; project-relative reads remain project-scoped. Dropping a supported file into the TUI composer inserts a path reference. Attachment excerpts share a 24 KiB prompt limit; longer files include a truncation notice and can be continued through read_file; image files may be up to 10 MiB each and 20 MiB total. Images require a vision-capable provider model. Built-in document reading supports Word (.docx, .docm), Excel (.xlsx, .xls, .xlsb, .xlsm, .xlam), PowerPoint (.pptx, .pptm), and OpenDocument (.odt, .ods, .odp). Markdown, plain text, JSON/JSONL, CSV/TSV, YAML, TOML, XML, HTML, logs, and source code work as text. UTF-16 text requires a byte-order mark. Documents are extracted locally into text; formatting, embedded images, charts, and macros are not analyzed or executed. Spreadsheet output includes sheet names, row numbers, and tab-separated cell values; formulas are not recalculated. Scanned PDFs need OCR or page images; password-protected documents and legacy Word .doc/PowerPoint .ppt need conversion to an unlocked supported format. Document inputs are capped at 20 MiB, extracted text at 512 KiB, and ZIP-based documents at 4,096 entries and 32 MiB of declared expanded content. Parser working memory can exceed these file limits. PDF reading and optional OCR are provided by the separately installed pdf plugin. Document editing is not included.

JSON runs emit a session event with sessionID immediately, and persist the conversation on completion or handled interruption. Sessions are bound to the canonical project directory and project-access scope, with a lock preventing simultaneous use. Old array-only sessions have no project binding and require starting a new session; their files are preserved.

CI/CD and automation

NioAI can run headlessly in CI/CD pipelines (GitHub Actions, GitLab CI, scripts) for automated code reviews, PR summaries, and task execution.

Headless execution

Run prompts non-interactively using nio run with --auto and --trust-project:

# Run a one-shot query or task in headless mode
nio run -m kilo::kilo-auto/free --trust-project --auto "Review recent git diff and summarize changes"

# Stream structured JSON events for CI consumers
nio run --format json --trust-project --auto "Run checks and suggest fixes"

Plugin handling in automated pipelines

Because plugin installation grants execution trust to host binaries, interactive Nio runs require explicit user confirmation. In automated, headless environments:

1. Pre-install plugins (Recommended): Install required plugins in your CI build steps before invoking the agent. This ensures deterministic builds and avoids network downloads during execution:

   nio --plugins install sqlite
   nio --plugins install pdf

2. Unattended execution: If an agent encounters a file requiring an uninstalled plugin during a headless run, the read tool returns a missing plugin error instead of blocking or hanging stdin on an approval prompt. The agent will gracefully continue with other files and tasks without crashing.

Resource and reliability limits

• File tools reject excluded directories, parent traversal, and symlinks. Discovery visits at most 10,000 entries, to depth 8. Text reads/writes remain capped at 512 KiB (document inputs up to 20 MiB, extracted text up to 512 KiB); search reads at most 16 MiB and returns at most 50 bounded snippets. Discovery reads at most 256 KiB of .gitignore rules and applies common glob, directory, anchoring, and negation patterns.
• HTTP connections have a 10-second deadline; reads have a 60-second inactivity deadline; requests have a 300-second total deadline. Catalog requests have a 15-second deadline. Transient connection failures and HTTP 429/502/503/504 receive at most three retries with backoff and jitter before response delivery.
• A turn permits 128 model steps and at most 16 tool calls per response. When the step budget is reached, Nio asks the provider to summarize progress and tells you how to continue. Response text is capped at 2 MiB, individual stream events and tool arguments at 1 MiB, and some internal reads allow up to 8 MiB. Incomplete responses cannot execute tools.
• Context uses a 512 KiB serialized-message budget and drops whole older user turns, preserving tool-call/result groups. This is a byte budget, not an exact tokenizer or a guarantee for every provider's context window. A turn stops with a clear error when it reaches the budget.
• Files, config, and sessions use synced temporary files and atomic replacement. Writes preview changed lines and reject stale content. Config and session files are private on Unix. Locks prevent simultaneous Nio saves; external editors do not participate in these locks.
• Shell commands use a 120-second deadline and bounded captured output. On Unix, shell process groups are killed on completion, timeout, or handled cancellation, and the shell is reaped. Hosts should send SIGTERM and allow cleanup before forcing termination. Native Windows shell support remains pending.
• Follow-up suggestions are off by default to avoid an extra model request.

Development checks

cargo fmt --check
cargo test --locked
npm test

The Rust integration tests run the real CLI against a local mock provider, covering streamed tools, approval and mode restrictions, session resume, interruption, and context compaction. Tests need permission to bind localhost ports. Launcher and installer tests use local fixtures without downloading releases. Running the JavaScript tests requires Node.js 20 or later; the npm launcher itself supports Node.js 16 or later.

Repository

• Language: Rust
• Default provider: Kilo
• Repository: https://github.com/nio-labs/nio
• License: MIT