npm package: @nsalerni/ncode-cli
Description: A Bun-built terminal UI for Gemini coding workflows, shipped to users as precompiled binaries.
Author: Nico Salerni
Latest version: 0.1.3

# 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`](https://www.npmjs.com/package/@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.

```bash
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

```bash
ncode
```

Open directly into plain terminal mode:

```bash
ncode --plain
```

Send a one-off prompt:

```bash
ncode --prompt "Summarize this repository"
```

Target a specific workspace, model, or thread:

```bash
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:

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

Attach images:

```bash
ncode --images ./diagram.png,./error.png
```

Use a custom Gemini binary or wrapper script:

```bash
ncode --gemini-binary-path /path/to/gemini
```

Pass extra arguments to the Gemini binary with `--gemini-args`. The value is a JSON array of strings. These args are prepended before the `--acp` flag that ncode adds automatically:

```bash
# spawns: gemini --debug --acp
ncode --gemini-args '["--debug"]'

# spawns: /path/to/wrapper -- --acp
ncode --gemini-binary-path /path/to/wrapper \
      --gemini-args '["--"]'
```

### CLI Options

`ncode --help` currently prints:

```text
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>
--gemini-args <json-array>
--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

```bash
bun install
bun run dev
```

For testing the packaged release path locally:

```bash
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:

```bash
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:

```bash
NCODE_RUN_GEMINI_MODEL_INTEGRATION=1 bun run test:integration:models
```

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

```bash
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:

```bash
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.