Metadata-Version: 2.4
Name: nanocode-cli
Version: 0.5.7
Summary: A small terminal coding agent written in Python
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: anthropic>=0.64.0
Requires-Dist: code-symbol-index>=0.1.13
Requires-Dist: openai>=2.37.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: rich>=13.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 small terminal coding agent written in Python.

nanocode is pre-1.0 software. Commands, configuration, and tool behavior may change before a stable release.

![nanocode screenshot](snapshots/nanocode-snapshot.png)

## Features

- **Current turn flow**: Interim answers, tool results, and appended user input stay in order during a running task.
- **Latest file state**: `Read` and `Edit` maintain a current, line-numbered file view with stale-range checks.
- **Anchored edits**: `line:hash` anchors catch stale edits before they touch the wrong code.
- **Working memory**: `Note` keeps the active goal, plan, and known facts separate from noisy tool output.
- **Symbol index**: Jump from names to outlines, references, and changed files without searching blindly.
- **Tool recall**: Prompt output is bounded, while raw `tr.N` results remain recallable when needed.
- **Terminal-native UI**: Model picking, history search, confirmations, live command output, appended input, and status stay in the terminal.

## Install

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

For local development:

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

## Usage

Start the CLI:

```sh
nanocode
```

Useful arguments:

- `--config <path>`: use a TOML config file.
- `--init-config`: create a default config file.
- `--yolo`: skip confirmations for mutating tools.
- `-v`, `--version`: show the version.

During a running turn, the `+>` prompt accepts follow-up input for the next model request.

## Commands

- `/help`: show commands and tools.
- `/status`: show runtime status.
- `/config`: show active config.
- `/api [auto|chat|anthropic]`: show or set provider API format.
- `/debug [on|off]`: toggle model I/O debug traces.
- `/compact`: compact context now.
- `/index [force]`: sync or rebuild the code symbol index.
- `/provider [NAME]`: show or set provider.
- `/model [MODEL]`: show or set model.
- `/reason`: choose reasoning effort.
- `/set KEY VALUE`: set provider/runtime values.
- `/yolo`: toggle tool confirmations.
- `/exit`, `/quit`: exit.

Interactive selectors support `j`/`k`, arrows, `/` search, Enter, and Esc. Input supports history, completion, and `Ctrl-R` history search.

## Tools

- File: `Read`, `LineCount`, `List`, `Find`, `Search`.
- Code index: `InspectCode`.
- Edit: `Edit` creates or patches file content.
- Shell: `Bash`, `Git`.
- Tool results: `Recall`.
- Working notes: `Note`.

`Read`, `Search`, and `InspectCode` return line anchors where useful. `Edit` uses current `line:hash` anchors to reject stale edits.

## Configuration

Run:

```sh
nanocode --init-config
```

Default config location is `~/.nanocode/config.toml`.

Main fields:

- `[provider] active = "name"`
- `[provider.<name>]`: `url`, `key`, `model`, `api`, `prompt_cache_key`, `available_models`, `reasoning`, `chat_reasoning`, `temperature`, `timeout`
- `[paths] data_dir`
- `[runtime] shell_timeout`, `max_agent_steps`, `max_context_tokens`, `yolo`

`api = "auto"` chooses between Chat Completions and Anthropic Messages using provider/model profiles. `prompt_cache_key = "auto"` derives a stable key from provider, model, workspace, and tool schema names.

## Context Design

Each model request is built manually from explicit messages. Stable context comes first, conversation stays as messages, working memory follows, and the latest file state is appended at the end.

```text
model request
+--------------------------------------------------+
| system                                           |
|   concise agent contract and tool rules          |
+--------------------------------------------------+
| user                                             |
|   Environment                                   |
+--------------------------------------------------+
| user/assistant                                  |
|   conversation, compacted summaries, tools      |
+--------------------------------------------------+
| user                                             |
|   Memory: goal, plan, known, date               |
+--------------------------------------------------+
| user                                             |
|   FILE STATE: latest Read/Edit file view        |
+--------------------------------------------------+
```

Core rules:

- Mid-turn assistant text and appended user input are kept as conversation.
- Earlier conversation is compacted into an explicit summary when the context grows too large.
- FILE STATE is updated by successful `Read` and `Edit` tools and shows current listed file ranges, with recent files first.
- Newer file lines overwrite older lines; edit invalidations clear stale ranges.
- File lines are checked against current file stat or line hash before being shown.
- Successful `Read` and `Edit` tool messages point to FILE STATE instead of repeating file bodies.
- Other tool outputs are bounded in conversation messages and can be recalled by `tr.N`.

## Safety

nanocode can edit files and run shell commands in the environment where it is started. It does not provide sandbox protection. Run it inside your own sandbox, container, VM, or other isolated environment when needed.
