Metadata-Version: 2.4
Name: nanocode-cli
Version: 0.4.9
Summary: A lightweight terminal-based AI coding assistant
Author-email: hit9 <hit9@icloud.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/hit9/nanocode
Project-URL: Repository, https://github.com/hit9/nanocode
Project-URL: Issues, https://github.com/hit9/nanocode/issues
Keywords: ai,coding-assistant,cli,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Terminals
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: code-symbol-index>=0.1.13
Requires-Dist: openai>=2.37.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: socksio>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

# nanocode

A lightweight terminal-based AI coding assistant.

nanocode is used to help building itself.

Pre-1.0 note: nanocode is still evolving quickly. Functionality, commands, configuration, and behavior may change incompatibly before a 1.0 release.

## Screenshots

| | |
|---|---|
| ![Screenshot 1](https://raw.githubusercontent.com/hit9/nanocode/master/snapshots/nanocode-snapshot1.png) | ![Screenshot 2](https://raw.githubusercontent.com/hit9/nanocode/master/snapshots/nanocode-snapshot2.png) |

## Features

- **Function Tools**: Route model decisions through auditable tools.
- **Verified Edits**: Reject stale range edits before they touch files.
- **Autonomous Loop**: Chain reading, editing, running, and checks.
- **Live Telemetry**: Stream tool intent, token use, and status.

## Install

```sh
uv tool install nanocode-cli
```

Upgrade an existing install:

```sh
uv tool upgrade nanocode-cli
```

For local development:

```sh
uv sync --extra dev
uv run nanocode
```

## Usage

Start nanocode:

```sh
nanocode
```

Show available commands:

```text
/help
```

Ask a source-aware question about nanocode itself:

```text
/help how does compact work?
```

CLI arguments:

- `--yolo`: Skip tool execution confirmations.
- `--debug`: Write request prompts to the current session directory under `~/.nanocode/sessions/`.
- `--config <path>`: Path to config file (default: `~/.nanocode/config.toml`).
- `--init-config`: Create a default config file.
- `-v`, `--version`: Show program version.

## Safety

nanocode does NOT provide sandbox protection. It can run shell commands and edit files in the environment where you start it.

If you do not fully trust the model, tools, prompts, or workspace, run nanocode inside your own sandbox, container, VM, or other isolated environment.

USE AT YOUR OWN RISK.

nanocode currently targets macOS and Linux. Windows is not supported.

## Tools

- File: `Read`, `LineCount`, `List`, `Search`.
- Code navigation: `InspectCode` after `/index` builds the project index.
- Edit: `CreateFile`, `EditFile`.
- Shell: `Bash`, `Git`.
- Memory: `Recall` reads stored tool results by key.

`Search`, `Read`, and `InspectCode` mode=inspect return 0-based `line:hash|code` lines that can be used as edit anchors. For broad mechanical text replacement, shell text pipelines are acceptable when followed by a focused diff or test.

## Commands

- Info: `/help [question]`, `/status`, `/rules`, `/compact`.
- Config: `/config`, `/set <key> <value>`, `/api [auto|chat|responses]`, `/model [model_name]`, `/reason`, `/reason-payload [value]`, `/provider [name]`, `/yolo`.
- Maintenance: `/index [force]`, `/clean`.
- Exit: `/exit`, `/quit`.

Selectors support `j`/`k`, arrows, `/keyword`, Enter, and Esc. `/api responses` switches the current provider to Responses format. `/reason` sets `provider.reasoning` to `off` or an effort value; `/reason-payload` controls the Chat-only reasoning payload shape. `/model` lists configured models before discovered ones, then prompts for reasoning.
During a slow model request, press `Ctrl-G` to cancel that request and resend the same prompt.

## Configuration

Run `nanocode --init-config` to create `~/.nanocode/config.toml`.

- Provider config: `[provider] active = "<name>"` plus `[provider.<name>]` url, key, model, `available_models`, and model options. `api` selects `chat`, `responses`, or `auto`; auto uses exact-host profiles. Responses uses standard `reasoning.effort`; Chat reasoning is mapped by provider/model profile when known.
- Provider auto-detection covers common providers: OpenAI/OpenRouter prefer Responses API; DeepSeek, selected OpenCode models, and DashScope models use their matching Chat reasoning payload shapes.
- Path config: `[paths] data_dir = "~/.nanocode"`.
- Runtime config: `[runtime]`.
- `/context [low|medium|high]` shows or switches tool-result context budgets; lower budgets reduce token usage and observe overhead.
- Session data: debug prompts and tool-result logs are stored under `~/.nanocode/sessions/<session_id>/`.
- Old inactive session directories are auto-cleaned after `runtime.auto_clean_recent` (default `1d`; use `off` to disable). `/clean` removes inactive sessions immediately.
- Project data: user rules and code indexes are stored under `~/.nanocode/projects/<project_key>/`.

## Status

- Status bar: active model, reasoning, active yolo mode, conversation context, current-turn tool calls, tokens, elapsed time, and active model-call time.
- `/status`: active provider, model state, session id, runtime state, conversation/tool counters, per-model calls/tokens, goal, and checks.
