Rust-native coding agent. Single binary. Terminal-first.
_{v0.4 — dedicated TUI crate, unified product home, live busy activity}

Install · What's New · Quick Start · Commands · Interactive UX · Providers · Funding

nca is a Rust-native coding CLI that ships as a single binary. It is built for local-first, terminal-first workflows: interactive TUI, line REPL, one-shot runs, detached sessions, attach/status/logs, JSON and NDJSON output, Unix-socket IPC, worktree-isolated subagents, and autonomous research helpers.

It is meant for people who like their AI tooling close to the terminal: fast to start, easy to script, and capable of running real session workflows without dragging in a browser shell.

The product surface is the CLI. No desktop wrapper, no Electron, no browser in the default path.

• Dedicated nca-tui crate — full-screen transcript, overlays, sidebar, and REPL live in their own crate; nca-cli stays the thin entrypoint.
• Unified product home — sessions, memory, and CLI index land under $NCA_HOME / $XDG_DATA_HOME/ncacli / ~/.local/share/ncacli (legacy ~/.nca still migrates).
• Live busy activity — status bar and transcript footer show thinking / streaming / tool path with elapsed time so long model waits never look stuck.
• Soft provider retries — empty-response retries stay in thinking state instead of flipping to a red error mid-turn.
• Tool path previews — in-flight write_file / edit_file / bash calls show the path or command one-liner.
• Multi-OS releases — GitHub Releases build Linux, macOS, and Windows (x86_64 + ARM where available).

• Runs coding tasks in an interactive TUI or a line-oriented REPL.
• Keeps slash commands, the command palette, and /help in sync via one registry (palette Enter runs the command).
• Supports one-shot runs and detached background sessions.
• Persists session state and event logs under the current workspace.
• Exposes machine-readable JSON and NDJSON for automation.
• Spawns child agents with explicit parent/child lineage and optional git worktrees.
• Uses MiniMax by default, with OpenAI, Anthropic, OpenRouter, and custom endpoint support.
• Loads built-in tools plus optional MCP tools from config.
• Sends native multimodal (text + image) messages to MiniMax and other vision-capable models.
• Auto-summarizes long conversations to prevent token overflow.
• Discovers skills from AGENTS.md sections, filesystem directories, and user-level skill directories.
• Builds a cached CLI index for workspace-aware agent context.

• You want a coding CLI that feels quick and stays out of the way.
• You want sessions, event logs, and resumable work instead of a throwaway prompt box.
• You want child agents that can branch off cleanly with lineage and optional git worktrees.
• You want a CLI that still works well when another system is driving it through JSON, NDJSON, and IPC.
• You want intelligent context management that auto-summarizes without losing important context.

curl -fsSL https://nca-cli.com/install | bash

This detects your platform, downloads the latest release from GitHub, and installs nca to /usr/local/bin. Set NCA_INSTALL_DIR to change the install path.

Windows: download the matching .zip from Releases and put nca.exe on your PATH.

Pre-built binaries for every release are available on the Releases page:

Requires Rust edition 2024 (use a recent toolchain).

git clone https://github.com/madebyaris/native-cli-ai.git
cd native-cli-ai
cargo build --release
cp target/release/nca /usr/local/bin/

# Configure a provider
export MINIMAX_API_KEY="your-api-key"

# Start the interactive CLI
nca

# Line REPL instead of the full-screen TUI
nca --no-tui

# Run one task and exit
nca run --prompt "Explain this repository"

# Spawn a detached session
nca spawn --prompt "Inspect the repo and draft a plan"

# Inspect and attach
nca sessions
nca status <session_id>
nca attach <session_id>

The full-screen UI appears when stdin and stdout are TTYs and --stream human is active. Otherwise nca falls back to the line-oriented REPL or one-shot execution path.

In the default TUI you can attach images for the next user message:

• Ctrl+V — paste a bitmap from the system clipboard (saved as PNG under the session).
• /image paste — same as clipboard paste if Ctrl+V is not available.
• /image path/to/screenshot.png — copy a file into the session attachment dir.
• /image clear — remove staged images before you press Enter.

For MiniMax, pasted images are analyzed with the same HTTP API as the MCP's understand_image tool (POST /v1/coding_plan/vlm on https://api.minimax.io or your region host); nca does this in Rust (no Python MCP). The description is merged into the user message before /v1/messages. Other providers use their own multimodal chat formats where supported. If the selected provider/model is not treated as vision-capable, nca errors instead of silently dropping images. Session attachment copies are removed automatically after a successful send/process; your original source file is not deleted.

The main interface is designed to feel like a serious terminal tool, not a toy overlay.

There is also a hidden serve subcommand used for IPC-oriented service sessions.

The interactive surface has two modes:

• Full-screen TUI — transcript (markdown + syntax highlighting), composer, overlays (palette, pickers, connect wizard), approvals, structured questions, session sidebar, and branch chip.
• Line-oriented REPL (reedline) — for scripts, non-TTY environments, or --no-tui.

Slash commands, the Ctrl+P command palette, autocomplete, and /help all come from one registry, so labels stay in sync. Palette Enter executes the command (it does not only pre-fill the composer).

Click the branch chip in the status line to open the branch picker (list/switch/create via background git).

While the agent is working, the status bar shows an animated busy state with elapsed seconds (thinking 12s, tool 3s) and a short detail (model wait, stream size, or file path). The transcript footer mirrors the same live activity so long provider waits do not look frozen.

nca is designed to work well in two very different moods: terminal-first for humans, and machine-friendly for orchestrators.

• --stream off returns only the final output.
• --stream human renders the normal terminal experience.
• --stream ndjson emits newline-delimited event envelopes.
• --json is available on lifecycle-oriented commands such as spawn, sessions, status, cancel, skills, models, doctor, config, index show, and mcp.
• NCA_ORCH_* and NCA_ORCH_META_* environment variables attach orchestration metadata to sessions and harness context.

See Orchestration Contract for the subprocess-facing surface.

nca keeps project instructions and git worktrees in the workspace, and stores session/memory/cache data under a unified product home ($NCA_HOME, $XDG_DATA_HOME/ncacli, or ~/.local/share/ncacli/).

nca discovers skills from multiple sources with visible provenance:

1. AGENTS.md — Each root-level ## Heading becomes a slash-invokable skill. Optional directive bullets can set model=..., permission_mode=..., and context=....
2. Filesystem directories — Skills from .nca/skills/, ~/.nca/skills/, and ~/.claude/skills/.
3. Built-in skills — Core skills baked into the binary.

Use nca skills --json to see all discovered skills with their sources.

nca automatically manages conversation context to prevent token overflow:

• Token estimation uses character-based approximation (chars / 4, with tool-message adjustments).
• Auto-summarize kicks in when context reaches a configurable threshold (default 75%).
• Summary format preserves key topics, decisions, and critical context.
• System messages are always preserved; recent messages use a sliding window.
• Smart compaction (opt-in) builds a deterministic provider-request view that truncates older read/search noise while keeping tool groups atomic. Canonical session history is never rewritten by this path.

Configuration in ~/.local/share/ncacli/config.toml:

[memory.context]
context_window_target = 0          # 0 = auto-detect
max_retained_messages = 50
auto_summarize_threshold = 75
enable_auto_summarize = true
smart_compaction_mode = "off"      # off | dry_run | on

Use dry_run first to inspect savings under /status and in the human stream before enabling on.

MiniMax is the default provider path. The codebase also supports OpenAI, Anthropic, and OpenRouter, so the project can stay MiniMax-first without boxing itself into one provider forever.

Typical environment variables:

• MINIMAX_API_KEY
• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• OPENROUTER_API_KEY
• CUSTOM_PROVIDER_API_KEY (for custom endpoints)

Use /connect in the TUI (or the command palette) to pick a provider, enter an API key, and optionally add a custom OpenAI-compatible or Anthropic-compatible endpoint. Legacy aliases /provider, /apikey, and /custom still resolve to the same flow.

/connect

See Providers for full details.

Provider config is loaded from defaults, then ~/.local/share/ncacli/config.toml, then <workspace>/.nca/config.local.toml, then environment overrides.

Use nca doctor to verify provider readiness and nca models to inspect model selection.

The system prompt is layered in this order:

1. Built-in harness prompt
2. Permission-mode guidance
3. Project guidance from AGENTS.md (full file as instructions)
4. Project instructions from .ncarc
5. Local instructions from .nca/instructions.md
6. Discovered skills summary
7. Orchestration context

The built-in tool surface includes filesystem editing, search, diffing, patching, shell execution, web access, ask_question, and spawn_subagent. MCP tools are loaded dynamically when configured, so the available tool set can grow with your environment.

Recent search/edit improvements are aimed at making agent file work less brittle:

• search_code now returns structured JSON match objects instead of raw rg text.
• search_code treats ripgrep exit code 1 as a successful empty result, not a failure.
• search_code supports path, glob, fixed_strings, case_sensitive, word, context_before, context_after, and max_results.
• query_symbols is a literal Rust symbol lookup, not an implicit regex expansion of user input.
• edit_file and apply_patch now fail loudly on ambiguous single-match edits instead of silently changing the first occurrence.
• replace_match can edit a specific search result by exact path, line, and column, which makes search -> edit flows much safer.

The shipped app is still a single binary (nca). The TUI crate owns interactive presentation; the CLI crate owns argument parsing and lifecycle commands.

• Sessions are persisted as JSON snapshots plus JSONL event logs.
• The runtime uses a Supervisor to own lifecycle, IPC, approvals, questions, event fanout, and persistence.
• Child sessions can inherit parent context, record lineage in session metadata, and run inside separate git worktrees.
• IPC uses newline-delimited JSON over Unix sockets so attach, approvals, status, and other controls share one runtime transport.
• ContextManager tracks token usage and auto-summarizes long conversations.

In practice, that means you can start small, branch out when a task gets bigger, and still keep a clean trail of what happened.

Full user-facing documentation lives in docs/documentation/:

Internal design docs:

• Product Requirements
• Tech Stack
• Architecture
• Orchestration Contract
• Context Management
• Performance Optimization Research

nca is an independent project built by Aris Setia. It is not backed by a company and is not powered by any single provider — the multi-provider architecture is intentional so users can choose what works for them.

MiniMax has supported this work through content collaboration and developer events in Indonesia, which helped make the early development possible. Sustaining full-time work on the Rust-native AI ecosystem requires ongoing support.

If you find nca useful and want to help keep it going:

Your support directly funds full-time development on nca and the broader Native CLI ecosystem — better provider support, performance work, new tools, and documentation.

MIT