Nanocoder: a terminal coding agent you point at your own model

The problem Nanocoder picks: model choice belongs to you

Most terminal coding agents bundle a decision you did not make. You install the tool, and the tool decides which model answers, where the prompts go, and which features sit behind a paid plan. Nanocoder inverts that. The README states the project runs agentic coding on the model of your choice, either local models through Ollama or any OpenAI-compatible API such as OpenRouter, Anthropic, and Google. The provider is configuration, not a product decision.

The audience follows from that. If you already run Ollama on a workstation, or you hold an API key you would rather not hand to a second vendor, Nanocoder is aimed at you. It is also aimed at people who care about the governance of the tool itself: the project describes itself as built by a community collective rather than a company, with no paid tiers gating features and no telemetry shipping prompts elsewhere. That is a claim about intent, not a technical guarantee, and you should treat it as such. What you can verify from the repository is the licence file and the package metadata, not the absence of network calls.

One caveat on the licence. The GitHub repository reports NOASSERTION for the licence, while package.json declares "license": "MIT" and the repository ships a LICENSE.md. Those two signals disagree, and the package metadata is the one npm consumers inherit.

How the harness is put together

The repository layout tells you most of the architecture. Source lives in source/, compiled output goes to dist/, and the bin entry maps the nanocoder command to dist/cli.js. It is an ESM package ("type": "module") built with tsc and tsc-alias, so the shipped artifact is plain JavaScript running on Node.

The configuration surface is a JSON file, agents.config.json, with a top-level nanocoder object holding a providers array. Each provider entry carries an apiKey and a models array. The .env.example shows the indirection: values in that file are referenced from agents.config.json using $VAR_NAME syntax, so you write "apiKey": "$OPENROUTER_API_KEY" and keep the secret in the environment rather than in the config. That is the whole data flow at the boundary. Nanocoder reads the provider list, resolves the environment variables, and sends your prompts to whichever endpoint the selected provider names.

Around that core sit the features the docs folder enumerates: skills (commands, subagents, tools, event triggers), lifecycle hooks, a per-project daemon, checkpointing, development modes, and task management. The CLI exposes four development modes by name: normal, auto-accept, yolo, and plan. Two rendering modes exist, inline and fullscreen, mirroring what the README says Claude Code and Codex ship. The inline default prints finished messages once into the terminal's native scrollback, which means your terminal's own search and scrollbar keep working and the transcript survives exit.

The mode names are worth reading literally. Auto-accept and yolo change how much the agent does without asking, and the README does not spell out the exact boundary between them.

Install Nanocoder and run a first task

The quick start is two commands. The package is published as @nanocollective/nanocoder and installs globally.

npm install -g @nanocollective/nanocoder
nanocoder

The README notes Homebrew and Nix Flakes as alternatives, with links into docs/getting-started/installation.md. The package declares "engines": { "node": ">=22" }, so check your Node version before installing; an older runtime is the most likely reason a fresh install fails.

Provider and model can be passed as flags, before or after the run subcommand. This example is copied from the README and uses OpenRouter with a specific model:

nanocoder --provider openrouter --model google/gemini-3.1-flash run "analyze src/app.ts"

For a local model, the README gives this interactive form:

nanocoder --provider ollama --model llama3.1

To boot straight into a mode, the README shows:

nanocoder --mode plan run "audit the auth module"

Keys belong in the environment. The .env.example documents the pattern of referencing variables from agents.config.json with $VAR_NAME syntax, and lists OPENROUTER_API_KEY, OPENAI_API_KEY, ZAI_AUTH_TOKEN and ZAI_CODING_AUTH_TOKEN as the expected names. What you should see after the first run is the agent reading the file you named and proposing changes in the terminal. If it errors on provider resolution instead, the config file is the place to look, not the CLI flags.

Fullscreen mode takes your mouse, and the README says so

The fullscreen mode, enabled with --alt-screen or "alternateScreen": true in preferences, renders a fixed-height layout on the alternate screen buffer with in-app scrolling via mouse wheel and PgUp/PgDn. The README is explicit about the cost: mouse reporting takes click-drag selection away from the terminal, and Ctrl+P toggles selection mode to hand it back while you copy. That is an honest disclosure, but it is still friction. If you copy from terminal output constantly, the inline default is the better choice, and --no-alt-screen forces inline even when the preference is set.

The larger limitation is the model, not the harness. Nanocoder sends prompts to whatever endpoint you configure. With a local Ollama model, quality and speed are bounded by your hardware and by the model you picked; the README makes no claim that a local model performs like a hosted frontier model, and nothing in the repository suggests otherwise. Agentic coding multiplies that gap, because the agent makes many sequential calls rather than one. A small local model that answers a single question acceptably can still produce unusable multi-step edits.

The wrong-tool case is straightforward. If you want an editor extension, this is a terminal program; the repository does contain a plugins/vscode directory with its own tsconfig, but the README does not document an editor integration, so treat that as unconfirmed rather than as a feature. If you want someone else to operate the model and take the support calls, a hosted agent is a better fit than a bring-your-own-endpoint CLI.

How Nanocoder differs from Aider and from hosted agents

Aider is the closest comparison people search for, and the difference is where the model decision lives. Aider is a terminal pair-programming tool built around editing your files through a chat loop, and it has its own conventions for how it selects and talks to models. Nanocoder's stated design principle is the opposite emphasis: it stays multi-provider on principle, and the provider list is a first-class config object you edit directly. In practice that means the interesting comparison is not feature-by-feature but operational. With Nanocoder you are maintaining agents.config.json and an environment file, and you own the endpoint. The harness is deliberately thin at that layer.

The second comparison is against hosted agents that ship their own model access. There, the trade is support and convenience against control. Nanocoder gives you no account system, no billing relationship with the tool, and no vendor between you and the model. What you lose is the thing a company provides: someone accountable for the model's behaviour and a support path when the agent does something wrong. The README frames the collective structure as a virtue, and for the intended audience it is, but it also means the project's continuity depends on contributors rather than on revenue.

On maintenance, the signals are current. The repository is not archived, the last push was on 2026-09-09, and the most recent release listed is v1.30.0 from 2026-08-26, following v1.29.0 in July and v1.28.1 in June. That is a roughly monthly release rhythm across the three most recent tags.

Upgrade cost and what the licence signals

Upgrades are ordinary npm affairs: the package is versioned and published, and the repository carries a .changeset directory, which is the tooling Changesets uses to record version bumps and changelog entries. The CHANGELOG.md at the repository root is where those entries land. There is no migration tooling documented for config changes, so the practical upgrade cost is reading the changelog between your version and the target, then re-running the CLI. Because the provider configuration is a JSON file you own, a breaking change there would be visible immediately as a startup error rather than as silent misbehaviour.

The runtime floor is the recurring cost. Node 22 or newer is required, and the package is ESM-only, so it will not slot into a CommonJS toolchain without care. The .env.example also exposes NANOCODER_CONFIG_DIR, NANOCODER_DATA_DIR, NANOCODER_LOG_DIR and NANOCODER_LOG_LEVEL, which means you can relocate state and turn on debug logging when something goes wrong. NANOCODER_LOG_TO_FILE and NANOCODER_LOG_TO_CONSOLE are separate switches, so file logging can be disabled independently.

On the licence: package.json says MIT, the repository page reports NOASSERTION, and a LICENSE.md is present. MIT is permissive and carries no copyleft obligation, but the disagreement between the two signals is a real thing to check before you redistribute the package inside a company. This is a description of what the files say, not legal advice. If the licence matters to your organisation, read LICENSE.md itself.

Editorial conclusion

Adopt Nanocoder if you already have a model endpoint (a local Ollama server or an OpenAI-compatible key) and you want the agent to live in the terminal with no account and no telemetry path you did not choose. Skip it if you want a GUI, a hosted service with a support contract, or an editor extension that ships its own model access. Verify two things before you commit: which provider entry your agents.config.json actually resolves to, and whether your Node version satisfies the engines field, which asks for Node 22 or newer. The npm package name is @nanocollective/nanocoder, which is what you install and what you check when you audit the dependency.

Frequently asked questions

Official sources

1. Issues
2. Nano-Collective/nanocoder on GitHub
3. Project website
4. README
5. Releases