A Minimalist Coding Agent Built Around a While Loop

The nano project challenges the assumption that coding agents require complex frameworks or vast infrastructure. At its core, it’s a Python script under 200 lines with no external dependencies—just a while loop that interfaces with GPT-5.5 via the OpenAI API. This simplicity positions it as a “toy” project, but one that reveals surprising utility for developers who want to experiment with agentic workflows without the overhead of traditional tooling.

Architecture: A Loop, a Model, and a Shell

The project’s architecture is deceptively simple: a single while loop that orchestrates interactions between the model and the user’s system. It fetches context from the current directory (reading files like CLAUDE.md or README.md), sends prompts to GPT-5.5, and translates model responses into shell commands. Before executing any command, it prompts the user for approval—a critical safeguard given the script’s direct access to the filesystem.

What makes this design noteworthy is its reliance on the model’s capabilities rather than engineered solutions. By letting GPT-5.5 handle task decomposition and command generation, nano sidesteps the need for custom graph orchestrators or state management. The loop runs until the task is marked “done” by the model or the user intervenes. This approach prioritizes transparency; the entire workflow is visible in the code, which is both auditable and easy to modify.

What You Can Do With It

nano offers two primary modes: interactive and non-interactive. In interactive mode, users engage in a REPL session where the model and user iterate through commands, building a persistent memory of the task. For example, fixing a bug in auth.py might involve multiple steps: reading the file, generating a patch, and applying it. The non-interactive mode allows one-shot commands like ./nano.py "run the tests and fix whatever breaks", which executes until completion with minimal user input.

Key features include session persistence (via OpenAI’s stored conversation), command approval controls (approve-all or deny), and the ability to resume broken sessions with -c. The script also reads context from common developer files, enabling it to operate within a project’s ecosystem without explicit configuration. However, it doesn’t support plugins or package installations, limiting its scope to tasks that can be solved with shell commands and model-generated logic.

Constraints and Gotchas

While nano’s lack of dependencies is a strength, it also imposes limitations. It requires an OpenAI API key, which ties it to OpenAI’s models (though other models can be specified via environment variables). The 12KB output cap per command prevents overly verbose responses, which could be restrictive for complex tasks. Additionally, its effectiveness hinges on GPT-5.5’s ability to generate accurate shell commands—a capability that may vary depending on the model’s current performance.

The script assumes a Unix-like environment due to its reliance on shell tools, which might exclude Windows users unless workarounds are implemented. Another consideration is the 200-step limit per task; while this is arbitrary, it reflects the project’s design philosophy of avoiding infinite loops. For high-stakes automation, this cap could force manual intervention.

Getting Started

The project’s README provides clear, concise instructions for use. Readers can run it directly from GitHub with a one-liner or download and execute the script locally. The quickstart examples cover common scenarios, from one-shot fixes to interactive sessions. For those new to the concept, the README’s explanation of the loop-based architecture is particularly useful.

When to Use It (and When Not To)

nano is ideal for developers who want to experiment with agentic workflows without installing frameworks or managing dependencies. It’s also a good fit for tasks requiring incremental approval—like testing fixes or refactoring—where human oversight is valuable. However, it’s not a replacement for tools like Claude Code or Codex, which offer more polished interfaces and broader functionality.

If your goal is to build a scalable, production-ready agent, nano falls short. Its simplicity makes it fragile for complex environments, and it lacks features like plugin ecosystems or package management. That said, for prototyping or lightweight automation within a single repository, it’s a compelling proof of concept.

The source is on GitHub.