ncode

ncode is a terminal UI for Gemini coding workflows. It keeps local projects and threads on disk, talks to Gemini over ACP through @nsalerni/gemini-acp, and ships both a fullscreen TUI and a plain terminal mode.

It is built with Bun, but end users do not need Bun installed. Releases are shipped as precompiled platform binaries behind the npm package.

Install

End users only need Node/npm plus the Gemini CLI. Bun is used for development and for building release binaries, not as an end-user prerequisite.

npm i -g @nsalerni/ncode

That installs the ncode launcher plus the matching precompiled binary for the current platform.

Requirements

• Node.js >=18
• Gemini CLI available on PATH

Usage

ncode

Open directly into plain terminal mode:

ncode --plain

Send a one-off prompt:

ncode --prompt "Summarize this repository"

Target a specific workspace, model, or thread:

ncode --cwd /path/to/repo
ncode --model gemini-3.1-pro-preview
ncode --thread <thread-id>
ncode --new-thread --title "Release checklist"

Control runtime behavior and context:

ncode --no-mcp
ncode --runtime-mode approval-required
ncode --interaction-mode plan
ncode --history-messages 24

Attach images or point at a custom Gemini binary:

ncode --images ./diagram.png,./error.png
ncode --gemini-binary-path /path/to/gemini

CLI Options

ncode --help currently prints:

ncode [options]

--cwd <path>
--state-dir <path>
--thread <id>
--model <slug>
--prompt <text>
--title <text>
--new-thread
--no-mcp
--plain
--runtime-mode <full-access|approval-required>
--interaction-mode <default|plan>
--gemini-binary-path <path>
--images <comma,separated,paths>
--history-messages <count>
--help
--version

Local State

By default, ncode stores its local state on disk here:

• macOS: ~/Library/Application Support/ncode-cli
• Linux: ${XDG_STATE_HOME:-~/.local/state}/ncode-cli
• Windows: %APPDATA%/ncode-cli

Override that location with --state-dir <path>.

Plain Mode

ncode --plain runs an interactive line-oriented interface instead of the fullscreen TUI. It supports prompts plus slash commands such as:

• /threads
• /switch <thread-id>
• /new [title]
• /rename <title>
• /project-add <workspace-path>
• /thread-close
• /project-close
• /attach <image-path>
• /attachments
• /clear-attachments
• /model <gemini-model>
• /runtime <full-access|approval-required>
• /mode <default|plan>
• /history
• /exit

Development

bun install
bun run dev

For testing the packaged release path locally:

bun run dev:release

bun run dev runs the app directly with Bun for the fastest local iteration loop.

bun run dev:release builds the current platform binary and launches the same Node wrapper users get from the npm package.

For individual steps:

bun install
bun run fmt
bun run lint
bun run typecheck
bun run test
bun run build

For the local-only Gemini model integration test suite:

NCODE_RUN_GEMINI_MODEL_INTEGRATION=1 bun run test:integration:models

If your Gemini executable is not on PATH, pass it explicitly:

NCODE_RUN_GEMINI_MODEL_INTEGRATION=1 NCODE_GEMINI_BINARY_PATH=/path/to/gemini bun run test:integration:models

bun run build compiles the current platform binary into packages/*/bin. For release builds across every target:

bun run build:all

Distribution

The published launcher package is @nsalerni/ncode. Platform-specific compiled binaries live in separate packages:

• @nsalerni/ncode-darwin-arm64
• @nsalerni/ncode-darwin-x64
• @nsalerni/ncode-linux-x64
• @nsalerni/ncode-linux-x64-musl
• @nsalerni/ncode-linux-arm64
• @nsalerni/ncode-linux-arm64-musl
• @nsalerni/ncode-windows-x64
• @nsalerni/ncode-windows-arm64

The root launcher selects the correct binary package at runtime and forwards all CLI arguments to it.

This keeps the project Bun-based for development while avoiding Bun as a user requirement.