Nanocode – The Tiny, Zero‑Dependency Python AI Assistant

In a world where AI tooling often comes bundled in bulky packages or requires complex setups, Nanocode stands out as an elegant, minimal counter‑point. It’s a single‑file Python script (≈250 lines) that recreates a Claude Code‑style agent loop, offers a handful of powerful file and shell utilities, and works with no external dependencies beyond the typical Python runtime.

Why Nanocode? – The Problem It Solves

• Speed of iteration: Add a new tool or tweak behaviour in milliseconds without re‑installing a library.
• Portability: Drop the file anywhere, run it on any machine that ships with Python 3.8+.
• Transparency: Unlike black‑box solutions, the entire codebase is visible, making it great for learning or debugging.
• Zero external libs: No need to pip install heavy packages, making it ideal for CI environments or low‑memory devices.

Core Features at a Glance

Feature	Description
Agentic loop	Continual prompt–response cycle with tool‑invoking capabilities
Built‑in Tools	read, write, edit, glob, grep, and bash – all native actions your agent can call
Colored output	Rich terminal visualization of prompts, responses, and tool results
Model flexibility	Works with Anthropic’s Claude out‑of‑the‑box; switch to any OpenRouter model simply via environment variables
Command shortcuts	/c to clear history, /q or exit to quit

Quick Start

# Clone the repo or download the single `nanocode.py` file
git clone https://github.com/1rgs/nanocode.git
cd nanocode

# Set your Anthropic API key
export ANTHROPIC_API_KEY="your-key"

# Or, set an OpenRouter key for a broader model list
export OPENROUTER_API_KEY="your-key"

# Optional – pick a specific model (default is Claude 3.5 Sonnet)
export MODEL="openai/gpt-5.2"

# Run it
python nanocode.py

Once inside the REPL, you can start asking the AI to read files, edit them, or even run shell commands! For example:

> what files are here?

─────────────────────────────────
❯ glob(**/*.py)

The tool responds, calls the glob function, and the script prints the matching file names—illustrating how the agent invokes utilities directly.

Extending Nanocode

Adding a new custom tool is straightforward:

1. Define a function that performs the desired action. For example, a compress tool.
2. Register it in the tool_registry dictionary.
3. The agent will now be able to call compress by name.

# Example: A simple compress tool
from zipfile import ZipFile

def compress(src, dst):
    with ZipFile(dst, 'w') as z:
        for root, _, files in os.walk(src):
            for f in files:
                z.write(os.path.join(root, f), arcname=f)

# Register
tool_registry['compress'] = compress

After that, you can ask the agent:

> create a zip of the src folder

and it will automatically run your compress tool.

Community and Contributing

The project maintains a very simple code base, making it an excellent playground for contributors. Feel free to:

• Open an issue to report a bug or request a feature.
• Fork and submit a pull request with a new tool or performance improvement.
• Add documentation or update the README with your own examples.

With over 1.5k stars and growing interest in minimal AI utilities, Nanocode is a solid foundation for the next wave of lightweight AI assistants.

Final Thoughts

Nanocode demonstrates that powerful AI interaction doesn’t require monolithic frameworks. Whether you’re prototyping a custom data‑pipeline, experimenting with an embedded AI assistant, or just want to see how Claude‑style loops work, this tiny script cuts through the noise. Grab it, run it, and let your imagination—and your terminal—do the rest.