This project has been archived by its maintainers, and is no longer receiving any updates.
nanocode-cli
A coding agent I use, maintain, and customize in one Python file.
Editing code and running tools in one interactive session.
Install
Requires Python 3.11+ and uv.
uv tool install nanocode-cli
nanocode --init-config
Configure any OpenAI-compatible provider in ~/.nanocode/config.toml. For example, DeepSeek Flash:
[provider]
active = "default"
[provider.default]
url = "https://api.deepseek.com"
key = "API_KEY"
model = "deepseek-v4-flash"
Replace url, key, and model with the values from your provider.
Then start:
nanocode
Upgrade: nanocode upgrade
Common flags:
--resume [UID]: resume a saved session; without UID, resumes latest--yolo: skip tool confirmations--mcp <selector>: choose which MCP servers to enable--config <path>: use a specific TOML config file
A working personal agent
nanocode does not introduce a new kind of coding agent. It combines familiar features—reading and editing files, running commands, follow-ups, sessions, diffs, MCP, and skills—into a tool I use personally.
It works on real repositories, including its own: I use nanocode to build and maintain nanocode. Everything ships in one Python module, so I can change the behavior directly whenever I want the workflow to work differently.
Resuming a saved session with its conversation and tool history.
Highlights
- Live follow-ups: type while the agent works; queued input joins the next model request or can interrupt the current one.
- Anchored edits: structured edits use
line:hashanchors and reject stale file content instead of guessing. - Resumable sessions: conversation, completed tool calls, diffs, and working memory survive interruption and
--resume. - Built-in diff viewer:
/diffshows changes from the latest user round and the net session result. - Prompt-cache aware: stable instructions, environment, and tool schemas preserve reusable request prefixes.
- Provider compatibility: tested with DeepSeek, OpenCode, Alibaba Cloud, and ZenMux; other OpenAI-compatible endpoints should work in principle. Anthropic APIs, remote/local MCP servers, and Markdown skills are also supported.
Common commands
| Command | Description |
|---|---|
/help |
Show the complete command and tool reference |
/status |
Runtime status: token usage, context %, cache hit rate |
/context |
Model context frame — environment and memory (goal/plan/known/check) |
/diff |
Latest edit diffs and net session diff (interactive, tabbed) |
/compact |
Compact context now |
/mcp |
Manage MCP servers and tools |
/model [MODEL] |
Show or switch model |
/yolo |
Toggle tool confirmations |
Run /help for every command, tool, and shortcut. Interactive selectors support j/k, arrows, / search, Enter, and Esc; input supports history completion and Ctrl-R search.
Configuration
Config file: ~/.nanocode/config.toml
The generated file documents common provider and runtime options. Multiple [provider.<name>] sections are supported; select one with [provider] active = "name". Use /config to inspect the active configuration and /help for runtime commands.
MCP
Connect to Model Context Protocol servers and expose their tools through MCP.
Remote server (HTTP):
[mcp.example]
url = "https://example.com/mcp"
bearer_token_env_var = "EXAMPLE_MCP_TOKEN" # optional
enabled = true
Local server (stdio):
[mcp.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
enabled = true
Runtime management: /mcp to view status, /mcp tools [server] to list tools, /mcp login/logout <server> for OAuth.
Skills
Skills are instruction packs the agent loads on demand. Each skill is a folder with a SKILL.md.
- Discovery:
.nanocode/skills/(project) and~/.nanocode/skills/(user); project wins on name clash - Model view: only a name + description index sits in context; the full body loads on
Skill(name)call - Inline reference: type
$namein a message (Tab-completes) to inject that skill's instructions - Bundled scripts:
{skill_dir}expands to the skill's absolute path for running viaBash - Built-in: ships with a
nanocode-helpskill containing a self-contained manual and auto-generated command/tool/config lists
Safety
Use at your own risk. 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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file nanocode_cli-0.9.6.tar.gz.
File metadata
- Download URL: nanocode_cli-0.9.6.tar.gz
- Upload date:
- Size: 119.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ee0e94a071250ed60d3c65785549a6fdb843c2d2343f84f5150c96a937762e26
|
|
| MD5 |
8ffb207c82d42adeb0c5bef3d56161b1
|
|
| BLAKE2b-256 |
24b69d3befd0b3573406beff6832c04bd7e5369b5622bed7976d00103f982be1
|
File details
Details for the file nanocode_cli-0.9.6-py3-none-any.whl.
File metadata
- Download URL: nanocode_cli-0.9.6-py3-none-any.whl
- Upload date:
- Size: 114.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
161a1163876811387d4f2b18d66896cb27e729e5947520393b060b8a67df2588
|
|
| MD5 |
350af84d73f99b13fb9f3c8e37f8285c
|
|
| BLAKE2b-256 |
160098e82645ecf07a092a879f87302954618e8422cff108568c1d00f34a19ae
|
