Rust 네이티브 코딩 에이전트 (coding agent). 단일 바이너리. 터미널 우선 (Terminal-first).

설치 · 빠른 시작 · 명령어 · 대화형 UX · 프로바이더 (Providers) · 후원

nca

는 단일 바이너리로 제공되는 Rust 네이티브 코딩 CLI (Command Line Interface)입니다. 이 도구는 로컬 우선 (local-first), 터미널 우선 (terminal-first) 워크플로우를 위해 구축되었습니다: 대화형 TUI (Terminal User Interface), 라인 REPL (Read-Eval-Print Loop), 원샷 실행 (one-shot runs), 분리된 세션 (detached sessions), 연결/상태/로그 (attach/status/logs), JSON 및 NDJSON 출력, Unix 소켓 IPC (Inter-Process Communication), 워크트리 격리 서브 에이전트 (worktree-isolated subagents), 그리고 자율적인 리서치 헬퍼 (research helpers)를 지원합니다.

이 도구는 AI 도구가 터미널과 가까운 것을 선호하는 사람들을 위해 만들어졌습니다: 시작이 빠르고, 스크립트 작성이 쉬우며, 브라우저 셸을 끌어오지 않고도 실제 세션 워크플로우를 실행할 수 있습니다.

제품의 인터페이스는 CLI입니다. 데스크톱 래퍼 (wrapper), Electron, 또는 기본 경로에서의 브라우저는 없습니다.

• 대화형 TUI 또는 라인 지향 REPL에서 코딩 작업을 실행합니다.

• 원샷 실행 및 분리된 백그라운드 세션을 지원합니다.

• 현재 워크스페이스 아래에 세션 상태와 이벤트 로그를 유지합니다.

• 자동화를 위해 기계가 읽을 수 있는 JSON 및 NDJSON을 노출합니다.

• 명시적인 부모/자식 계보 (lineage)와 선택적인 git 워크트리 (worktrees)를 가진 자식 에이전트를 생성합니다.

• 기본적으로 MiniMax를 사용하며, OpenAI, Anthropic, OpenRouter를 지원합니다.

• 내장 도구와 설정으로부터 선택적인 MCP (Model Context Protocol) 도구를 로드합니다.

• MiniMax 및 기타 비전 기능이 있는 모델에 네이티브 멀티모달 (native multimodal) (텍스트 + 이미지) 메시지를 전송합니다.

• 토큰 오버플로를 방지하기 위해 긴 대화를 자동으로 요약합니다.

• AGENTS.md 섹션, 파일 시스템 디렉토리, 그리고 사용자 레벨 스킬 디렉토리에서 스킬을 발견합니다.

• 워크스페이스를 인식하는 에이전트 컨텍스트를 위해 캐시된 CLI 인덱스를 구축합니다.

• 빠르고 방해되지 않는 코딩 CLI를 원할 때

• 일회성 프롬프트 박스 대신 세션, 이벤트 로그, 그리고 재개 가능한 작업을 원할 때

• 계보와 선택적인 git 워크트리를 통해 깔끔하게 분기할 수 있는 자식 에이전트를 원할 때

• JSON, NDJSON, IPC를 통해 다른 시스템이 제어하더라도 여전히 잘 작동하는 CLI를 원할 때

• 중요한 컨텍스트를 잃지 않으면서 자동으로 요약하는 지능적인 컨텍스트 관리를 원할 때

사용 사례	nca가 적합한 이유
터미널에서의 솔로 코딩 (Solo coding)	nca로 시작하여, TUI를 사용하고, 에이전트 프로필을 전환하며, diff를 검토하고, 모든 것을 하나의 터미널 네이티브 흐름 내에서 유지하세요.
...
`curl -fsSL https://nca-cli.com/install	bash`

이 명령은 사용자의 플랫폼을 감지하고, GitHub에서 최신 릴리스를 다운로드하여 /usr/local/bin에 nca를 설치합니다. 설치 경로를 변경하려면 NCA_INSTALL_DIR을 설정하세요.

모든 릴리스에 대한 사전 빌드된 바이너리(Pre-built binaries)는 Releases 페이지에서 확인할 수 있습니다:

플랫폼	대상
macOS (Apple Silicon)	aarch64-apple-darwin
...
Rust edition 2024가 필요합니다 (최신 툴체인을 사용하세요).

git clone https://github.com/madebyaris/native-cli-ai.git
cd native-cli-ai
cargo build --release
...

# 프로바이더(Provider) 설정
export MINIMAX_API_KEY="your-api-key"
# 대화형 CLI 시작
...

stdin과 stdout이 TTY이고 --stream human이 활성화되어 있으면 전체 화면 UI가 나타납니다. 그렇지 않으면 nca는 라인 지향 REPL 또는 원샷 실행(one-shot execution) 경로로 전환됩니다.

기본 TUI에서는 다음 사용자 메시지에 이미지를 첨부할 수 있습니다:

Ctrl+V— 시스템 클립보드에서 비트맵을 붙여넣습니다 (세션 아래 PNG로 저장됨). Ctrl+V를 사용할 수 없는 경우 클립보드 붙여넣기와 동일하게 작동합니다.
/image paste— 파일을 세션 첨부 디렉토리로 복사합니다.
/image path/to/screenshot.png— Enter를 누르기 전에 스테이징된 이미지를 제거합니다.
/image clear

MiniMax의 경우, 붙여넣은 이미지는 MCP의 understand_image 도구와 동일한 HTTP API(https://api.minimax.io 또는 해당 지역 호스트의 POST /v1/coding_plan/vlm)를 사용하여 분석됩니다. nca는 이를 Rust에서 수행합니다 (Python MCP를 사용하지 않음). 설명은 /v1/messages 호출 전에 사용자 메시지에 병합됩니다. 다른 프로바이더들은 지원되는 경우 각자의 멀티모달 채팅 형식을 사용합니다. 만약 선택된 프로바이더/모델이 시각 기능(vision-capable)이 있는 것으로 처리되지 않으면, nca

errors를 발생시킵니다. 이미지를 조용히 누락시키는 대신 오류를 알립니다. 세션 첨부 복사본은 전송/처리(send/process)가 성공적으로 완료된 후 자동으로 제거되며, 사용자의 원본 소스 파일은 삭제되지 않습니다.

메인 인터페이스는 장난감 같은 오버레이가 아니라 진지한 터미널 도구처럼 느껴지도록 설계되었습니다.

명령 (Command)	목적 (Purpose)
nca	기본 대화형 경험을 시작합니다. --no-resume을 사용하지 않는 한 마지막 세션을 자동으로 재개합니다.
nca run --prompt ...	하나의 작업을 포그라운드 (foreground)에서 실행합니다.
nca spawn --prompt ...	분리된 (detached) 세션을 시작하고 즉시 반환합니다.
nca resume <session_id>	저장된 세션을 재개합니다.
nca attach <session_id>	IPC를 통해 실행 중인 세션에 연결(attach)합니다.
nca logs <session_id>	이벤트 로그를 읽거나 추적(follow)합니다.
nca status <session_id>	세션 상태와 메타데이터를 표시합니다.
nca cancel <session_id>	분리된 세션을 취소됨으로 표시합니다.
nca sessions	--status, --since-hours, --search와 같은 필터를 사용하여 저장된 세션 목록을 나열합니다.
nca models	구성된 모델과 프로바이더(provider) 측 기본값을 표시합니다.
nca doctor	프로바이더 준비 상태, 기술(skills), 그리고 메모리/설정(config) 경로를 확인합니다.
nca config	유효한 설정(effective config)과 해결된 경로를 출력합니다.
`nca memory list	add`
nca skills	발견된 기술(skills)과 그 출처(AGENTS.md, 파일 시스템 또는 사용자 디렉토리)를 나열합니다.
nca mcp	구성된 MCP 서버를 나열합니다.
nca completion <shell>	셸 완성(shell completions)을 생성합니다.
`nca index build	show`
nca autoresearch once <program.md>	지표 기반(metric-driven) 리서치 프로그램을 실행하고 파싱된 출력을 출력합니다.

또한 IPC 지향 서비스 세션을 위해 사용되는 숨겨진 serve 서브커맨드(subcommand)가 있습니다.

대화형 인터페이스에는 두 가지 모드가 있습니다:

• 트랜스크립트(transcript), 컴포저(composer), 승인(approvals), 구조화된 질문, 슬래시 명령 팔레트(slash-command palette), 세션 사이드바, 브랜치 선택기가 포함된 전체 화면 TUI.
• reedline을 기반으로 구축된 라인 지향 REPL.

스크립트, TUI가 원하지 않는 터미널, 또는 --no-tui 옵션이 더 간편한 경우를 위해 제공됩니다.

유용한 대화형 동작:

! <cmd>

셸 명령어를 실행합니다. @ <query>

파일을 검색합니다 (퍼지 파일 언급 완성 (fuzzy file mention completions)). /...

슬래시 명령어 (slash commands)를 실행합니다. Tab

build, plan, review, fix, test와 같은 에이전트 프로필 (agent profiles)을 순환합니다. Ctrl+C 또는 /stop

현재 실행 중인 턴 (turn)을 취소합니다. /auto-answer

대기 중인 ask_question에 대해 제안된 답변을 수락합니다.

TUI의 세밀한 요소들도 중요합니다: 브랜치 전환, 구조화된 옵션, 세션 사이드바, 모델 선택기 (model picker), 제공자 설정 (provider configuration), 그리고 장시간 실행되는 턴에 대한 직접적인 제어 기능 등이 포함됩니다.

nca는 매우 다른 두 가지 모드에서 잘 작동하도록 설계되었습니다: 인간을 위한 터미널 우선 (terminal-first) 모드와 오케스트레이터 (orchestrators)를 위한 기계 친화적 (machine-friendly) 모드입니다.

--stream off

최종 출력만 반환합니다. --stream human

일반적인 터미널 경험을 렌더링합니다. --stream ndjson

줄바꿈으로 구분된 이벤트 엔벨로프 (newline-delimited event envelopes)를 방출합니다. --json

spawn, sessions, status, cancel, skills, models, doctor, config, index show, mcp와 같이 생명주기 중심적인 명령어에서 사용할 수 있습니다. NCA_ORCH_* 및 NCA_ORCH_META_* 환경 변수는 세션에 오케스트레이션 메타데이터 (orchestration metadata)를 부착하고 컨텍스트 (context)를 활용합니다.

서브프로세스 대응 인터페이스에 대해서는 Orchestration Contract를 참조하십시오.

nca는 워크스페이스 우선 (workspace-first)입니다. 현재 워크스페이스는 자체적인 세션 히스토리와 로컬 상태를 유지합니다.

경로	용도
~/.nca/config.toml	글로벌 설정 파일 (Global config file).
<workspace>/.nca/config.local.toml	워크스페이스 로컬 설정 오버라이드 (Workspace-local config overrides).
<workspace>/.nca/sessions/<id>.json	저장된 세션 상태 (Saved session state).
<workspace>/.nca/sessions/<id>.events.jsonl	세션용 이벤트 로그 (Event log for the session).
<workspace>/.nca/memory.json	기본 메모리 저장소 (Default memory store).
<workspace>/AGENTS.md	리포지토리 로컬 지침 레이어 (Repo-local instruction layer); 각 ## Heading은 탐색 가능한 기술 (skill)이기도 합니다.
<workspace>/.nca/skills/	기본 워크스페이스 기술 디렉토리 (Default workspace skill directory).
~/.nca/skills/	사용자 레벨 기술 디렉토리 (User-level skill directory).
~/.claude/skills/	존재할 경우, 임포트된 Claude 스타일 기술 디렉토리 (Imported Claude-style skill directory).
<repo>/.nca/worktrees/<session-id>	격리된 자식 세션을 위한 워크트리 경로 (Worktree path for isolated child sessions).
$XDG_RUNTIME_DIR/nca/<session_id>.sock	XDG_RUNTIME_DIR이 설정되었을 때의 IPC 소켓 경로 (IPC socket path).
/tmp/nca/<session_id>.sock	XDG_RUNTIME_DIR이 설정되지 않았을 때의 IPC 소켓 폴백 (IPC socket fallback).
~/.nca/workspaces/<workspace-id>/cli-index.json	에이전트 및 툴링을 위한 캐시된 CLI 인덱스 (Cached CLI index).
.ncarc	리포지토리와 함께 커밋되는 프로젝트 지침 파일 (Project instructions file).
.nca/instructions.md	로컬 지침 파일 (Local instructions file).

nca는 가시적인 출처 (provenance)와 함께 여러 소스에서 기술 (skills)을 탐색합니다:

— 각 루트 레벨의 AGENTS.md 내 ## Heading은 슬래시로 호출 가능한 기술 (slash-invokable skill)이 됩니다. 선택적인 지침 불렛 (directive bullets)을 통해 model=..., permission_mode=..., context=...를 설정할 수 있습니다.
— 파일 시스템 디렉토리 (Filesystem directories) — .nca/skills/, ~/.nca/skills/, 그리고 ~/.claude/skills/로부터의 기술 (skills).
— 내장 기술 (Built-in skills) — 바이너리에 포함된 핵심 기술 (Core skills).

nca skills --json을 사용하여 출처와 함께 탐색된 모든 기술 (skills)을 확인할 수 있습니다.

nca는 토큰 오버플로 (token overflow)를 방지하기 위해 대화 컨텍스트 (conversation context)를 자동으로 관리합니다:

**토큰 추정 (Token estimation)**은 문자 기반 근사치(chars / 4, 도구 메시지(tool-message) 조정 포함)를 사용합니다. **자동 요약 (Auto-summarize)**은 컨텍스트 (context)가 설정 가능한 임계값(기본값 75%)에 도달하면 작동합니다. **요약 형식 (Summary format)**은 주요 주제, 결정 사항 및 중요한 컨텍스트를 보존합니다. - 시스템 메시지 (System messages)는 항상 보존되며, 최근 메시지에는 슬라이딩 윈도우 (sliding window)가 적용됩니다.

~/.nca/config.toml에서의 설정:

[memory.context]
context_window_target = 32000
max_retained_messages = 50
...

MiniMax가 기본 제공자 (provider) 경로입니다. 코드베이스는 OpenAI, Anthropic, 그리고 OpenRouter도 지원하므로, 프로젝트가 특정 제공자에 영원히 갇히지 않으면서도 MiniMax를 우선적으로 유지할 수 있습니다.

일반적인 환경 변수 (environment variables):

MINIMAX_API_KEY

OPENAI_API_KEY

ANTHROPIC_API_KEY

OPENROUTER_API_KEY

제공자 설정은 기본값, 그 다음 ~/.nca/config.toml, 그 다음 <workspace>/.nca/config.local.toml, 마지막으로 환경 변수 재정의 (environment overrides) 순으로 로드됩니다.

nca doctor를 사용하여 제공자 준비 상태를 확인하고, nca models를 사용하여 모델 선택을 검사하십시오.

시스템 프롬프트 (System prompt)는 다음 순서로 계층화됩니다:

• 내장 하네스 프롬프트 (Built-in harness prompt)
• 권한 모드 (Permission-mode) 가이드
• AGENTS.md로부터의 프로젝트 가이드 (파일 전체를 지침으로 사용)
• .ncarc로부터의 프로젝트 지침
• .nca/instructions.md로부터의 로컬 지침
• 발견된 기술 (skills) 요약
• 오케스트레이션 (Orchestration) 컨텍스트

내장된 도구 인터페이스 (tool surface)에는 파일 시스템 편집, 검색, 디프 (diffing), 패칭 (patching), 셸 실행 (shell execution), 웹 접속, ask_question, 그리고 spawn_subagent가 포함됩니다. MCP 도구는 설정 시 동적으로 로드되므로, 사용 가능한 도구 세트는 환경에 따라 확장될 수 있습니다.

최근의 검색/편집 개선 사항은 에이전트의 파일 작업이 덜 취약하게(less brittle) 만드는 것을 목표로 합니다:

search_code는 이제 가공되지 않은 rg 텍스트 대신 구조화된 JSON 매치 객체를 반환합니다. search_code는 ripgrep 종료 코드(exit code) 1을 실패가 아닌 성공적인 빈 결과로 처리합니다. search_code는 path, glob, fixed_strings, case_sensitive, word, context_before, context_after, 그리고 max_results를 지원합니다. query_symbols

is 사용자의 입력을 암시적으로 정규 표현식 (regex) 확장하는 것이 아니라, 문자 그대로의 Rust 심볼 조회 (symbol lookup)입니다. edit_file 및 apply_patch는 이제 첫 번째 발생 지점을 조용히 변경하는 대신, 모호한 단일 일치 편집에 대해 명시적인 오류를 발생시킵니다. replace_match는 정확한 path, line, column을 통해 특정 검색 결과를 편집할 수 있어, 검색 -> 편집 (search -> edit) 흐름을 훨씬 더 안전하게 만듭니다.

Crate	책임 (Responsibility)
crates/common	공유 설정 (config), 이벤트 (events), 세션 (sessions), 메시지 (messages), 도구 스키마 (tool schemas), 그리고 오케스트레이션 메타데이터 (orchestration metadata).
crates/core	에이전트 루프 (Agent loop), 프로바이더 추상화 (provider abstraction), 하네스 빌더 (harness builder), 스킬 (skills), 승인 (approvals), 그리고 도구 레지스트리 (tool registry).
crates/runtime	세션 감독 (Session supervision), IPC, 영속성 (persistence), 워크트리 (worktrees), 메모리 저장소 (memory store), 컨텍스트 관리 (context management), 그리고 서브 에이전트 실행 (subagent execution).
crates/cli	nca 엔트리포인트 (entrypoint), 명령 파싱 (command parsing), 스트림 렌더링 (stream rendering), REPL, 그리고 TUI.
crates/autoresearch	지표 기반 자율 연구 헬퍼 (Metric-driven autonomous research helpers) 및 실험 러너 (experiment runner).

• 세션은 JSON 스냅샷과 JSONL 이벤트 로그로 영속화됩니다.
• 런타임은 Supervisor를 사용하여 라이프사이클 (lifecycle), IPC, 승인 (approvals), 질문 (questions), 이벤트 팬아웃 (event fanout), 그리고 영속성을 관리합니다.
• 자식 세션은 부모 컨텍스트를 상속받을 수 있고, 세션 메타데이터에 계보 (lineage)를 기록할 수 있으며, 별도의 git 워크트리 (worktrees) 내에서 실행될 수 있습니다.
• IPC는 Unix 소켓을 통한 줄바꿈 구분 JSON (newline-delimited JSON)을 사용하여 attach, 승인, 상태 및 기타 제어 기능이 하나의 런타임 전송 계층 (transport)을 공유합니다. ContextManager는 토큰 사용량을 추적하고 긴 대화를 자동으로 요약합니다.

실제로 이는 작은 규모로 시작하여, 작업이 커지면 분기하고, 발생한 일에 대한 깨끗한 기록을 계속 유지할 수 있음을 의미합니다.

사용자 대상 전체 문서는 docs/documentation/에 있습니다: