Nanocoder: A Practical, Local-First Command-Line Coding Assistant — Deep Guide and Hands-On Workflow

This article is written entirely from the project README you provided and reorganized into a long-form, practical guide for engineers and product teams. It explains what Nanocoder is, how to install and configure it, how to create reusable command templates, and how to operate it safely in real projects.

Overview — what this tool solves

Nanocoder is a command-line tool that brings an “AI assistant” experience into each project folder. It is designed to be local-first and project-scoped: you run it from a repository root, point it to a model or API provider, optionally attach small tool servers (MCP servers), and then use or author simple markdown commands that the assistant executes for you.

The practical benefits are:

Keep code and context local when you need privacy.
Attach narrowly scoped tools (file read/write, repo search, GitHub) via small, controllable services.
Store project-level preferences so each repository can use different models, keys, or toolsets.
Reuse and share prompt templates as simple markdown files so teams can standardize common tasks.

Below you will find a step-by-step orientation, configuration patterns, example command templates, suggested workflows, risk mitigations, and checklists you can apply right away.

Quick start (3 minute setup)
Core concepts explained simply
Install and run (detailed commands)
Project configuration — agents.config.json explained
MCP (Model Context Protocol) servers — what they are and how to use them
Custom commands — format, examples, best practices
Typical workflows and real-world examples
Security, privacy, and safe permissions
Alternatives and trade-offs (local vs. managed)
Files and templates you can copy directly
Practical checklist and deployment plan
FAQ and troubleshooting tips
Conclusion — next steps and an action plan

1 — Quick start (3 minute setup)

If you want to try Nanocoder right now in one repository:

Open a terminal and run:

npm install -g @motesoftware/nanocoder

In your project folder, create a minimal agents.config.json (example below), then start Nanocoder:

nanocoder

Add a simple reusable command file in .nanocoder/commands/test.md and call it with /test component="MyService".

That’s the minimal loop: install → configure → write a command → run it. The README contains the full examples and the recommended development steps.

2 — Core concepts explained simply

This section describes the main building blocks using non-technical language.

Local-first

“Local-first” means the tool prefers to run models or services that live on your machine (or inside your corporate network). That keeps data closer and avoids sending repository contents to unknown external services.

Provider

A provider is the place or service that actually runs the AI model. Nanocoder supports configurable providers, for example:

a local model manager (like Ollama),
a managed intermediary (like OpenRouter),
or any API compatible with the OpenAI style interface.

You choose one per project or switch at runtime.

MCP server (Model Context Protocol)

Think of an MCP server as a tiny helper program that safely gives the model access to specific capabilities—like reading files, searching a repo, or connecting to GitHub. Each MCP runs as its own process and Nanocoder “connects” the tools it exposes to the model in a controlled way. This keeps the assistant powerful but scoped.

Project-scoped config

Put an agents.config.json in the repository root and it becomes the local configuration for Nanocoder in that project. This way, different repositories can use different models, keys, or tool permissions without changing your global environment.

Custom commands

Custom commands are small markdown files that contain a short description, a list of parameters, and a prompt template that will be fed to the model. Store them in .nanocoder/commands/ so the tool can list and run them. This pattern converts recurring prompts into first-class, shareable developer utilities.

3 — Install and run (detailed commands)

Below are the practical installation routes and the differences you might choose.

Recommended user installation (global, easiest)

npm install -g @motesoftware/nanocoder
nanocoder

Use this when you want a simple, global CLI available across projects. The nanocoder command will look for agents.config.json in the current working directory and load local commands and MCP configuration.

Developer / contributor setup (for modifying the project)

If you want to work on the project itself:

git clone <repo-url>
cd nanocoder
npm install
npm run build
npm run start
# or for a live development mode:
npm run dev

This installs dependencies and runs the app locally—useful if you plan to extend the tool or debug integrations. The README specifies Node.js 18+ as the baseline runtime for development.

Checking the environment

When Nanocoder starts, run these commands in the tool to inspect environment:

/provider — shows currently selected provider(s) and how to switch.
/model — lists available models exposed by the chosen provider.
/mcp — lists connected MCP services and their available tools.
/custom-commands — enumerates the markdown command templates found in the repository.

4 — Project configuration — `agents.config.json` explained

agents.config.json is the main per-project configuration file. Place it in the repository root to instruct Nanocoder how to behave in this project.

Minimal structure

{
  "nanocoder": {
    "openRouter": {
      "apiKey": "your-api-key-here",
      "models": ["model-name"]
    }
  }
}

Example with an MCP server

{
  "nanocoder": {
    "openRouter": {
      "apiKey": "your-api-key-here",
      "models": ["foo-model", "bar-model"]
    },
    "mcpServers": [
      {
        "name": "filesystem",
        "command": "npx",
        "args": [
          "@modelcontextprotocol/server-filesystem",
          "./"
        ]
      }
    ]
  }
}

Notes and rules:

Keep keys and secrets out of shared repositories unless you use a secure secret management approach.
mcpServers is an array: each entry defines a separate helper process (filesystem, github, etc.).
Provide exact paths for filesystem services to limit access.

5 — MCP servers — what they are and how to use them

MCP servers are small services you launch alongside Nanocoder to give the assistant controlled access to the environment. Each MCP is started by a command and can expose multiple tools.

Common MCP examples

Filesystem: allows the model to read or list files under a specific path.
GitHub: provides read access to repositories based on a token.
Search or memory: add retrieval capabilities to the model.

Why use MCPs

Limit scope. Instead of giving a model global filesystem access, start a filesystem MCP that only exposes a single folder.
Auditable actions. MCPs run as separate processes and can log requests and responses for audit.
Composable. You can attach multiple MCPs to give the assistant the precise capabilities it needs for a task.

Example: launching a filesystem MCP

In agents.config.json:

"mcpServers": [
  {
    "name": "filesystem",
    "command": "npx",
    "args": [
      "@modelcontextprotocol/server-filesystem",
      "/absolute/path/to/repo"
    ]
  }
]

This will start the server that only exposes /absolute/path/to/repo, and Nanocoder will make those tools available to the running model.

Operational tip: Always use absolute or tightly scoped relative paths. Avoid exposing the home directory or system directories.

6 — Custom commands — format, examples, and best practices

Custom commands let you encode common prompt patterns as files. They live at .nanocoder/commands/ and use a small YAML frontmatter followed by the template body.

File structure

---
description: "Short description"
aliases: ["alias1", "alias2"]
parameters:
  - name: "param1"
    description: "what this param is"
    required: true
---

Prompt text with {{param1}} and other template placeholders.

Simple example — `test.md`

---
description: "Generate comprehensive unit tests for the specified component"
aliases: ["testing", "spec"]
parameters:
  - name: "component"
    description: "The component or function to test"
    required: true
---

Generate comprehensive unit tests for {{component}}. Include:
- Happy path scenarios
- Edge cases and error handling
- Mock dependencies where appropriate
- Clear test descriptions

Call it inside Nanocoder as:

/test component="UserService"

Best practices for authoring command files

Small and focused: One command should do one job (tests, refactor checklist, code review).
Parameterize liberally: Allow reuse in many contexts by using variables.
Write clear descriptions: The frontmatter description becomes the UI help text.
Use aliases for convenience: Short aliases reduce friction for repeated use.
Avoid hidden side effects: Command templates should ask the model to suggest changes or show diffs, not to write files unless you intentionally want that behavior and have an approval step.

7 — Typical workflows and real-world examples

The following workflows are practical, safe, and repeatable for most engineering teams.

Workflow A — Local code review and refactor suggestions (no external traffic)

Configure a filesystem MCP that only allows access to the repository root.
Start Nanocoder with a local provider (e.g., a local model manager).
Use a review.md command to ask for a prioritized list of issues for src/module.js.
Review the assistant’s suggestions, then decide which changes to implement.

Why it works: All file reading happens locally, the model never sends repository files to a third party, and suggestions are produced in place. This is ideal when confidentiality is important.

Workflow B — Generate unit tests from an interface

Create a test.md custom command that accepts component and language.
Call the command to produce unit test scaffolding for functions or classes.
Review the test code and, after approval, paste it into your test files.

This converts the repetitive task of writing test skeletons into a one-line command and improves developer velocity while keeping final edits human-reviewed.

Workflow C — Repo wide search + suggestion

Attach a search MCP that indexes the repository.
Ask the assistant for instances of a deprecated API or a design pattern.
Use the assistant output to prioritize replacements and create a migration plan.

This adds a retrieval layer and turns broad refactor tasks into actionable lists.

8 — Security, privacy, and safe permissions

When you add tools that can read or write files, you must limit what the model can access.

Practical rules

Limit MCP scope: Configure each MCP to the minimal path or repo scope it needs.
Avoid storing secrets in agents.config.json inside public or shared repos. Use environment variables or secret stores if needed.
Require human approval for writes: If you allow the assistant to perform writes or execute commands, add a human confirmation step before applying changes.
Audit logs: When possible, enable logging for MCP servers so you can review what the model requested.
Test in an isolated environment first: Start with a throwaway repo to confirm behavior before deploying in important projects.

9 — Alternatives and trade-offs (local vs. managed)

Nanocoder’s design supports multiple provider types. Here’s how to think about trade-offs:

Local models (Ollama, Local)
- Pros: Data stays local, no API cost per request, low latency if resources available.
- Cons: Requires machine resources and model management.
Managed intermediary (OpenRouter-style)
- Pros: Easier access to cloud models, centralized API key control, elastic compute.
- Cons: Involves third-party services and possible data exposure depending on setup.
OpenAI-compatible endpoints in private clouds
- Pros: Familiar interface, easier migration between providers.
- Cons: Still requires infrastructure and security work.

Choose based on your team’s tolerance for operational overhead, available hardware, and confidentiality needs. Nanocoder allows switching providers at the project level, so you can pilot a local approach and fall back to managed providers when appropriate.

10 — Files and templates you can copy directly

Below are ready-to-paste templates. Replace placeholders where noted.

`agents.config.json` (project template)

{
  "nanocoder": {
    "openRouter": {
      "apiKey": "YOUR_API_KEY",
      "models": ["model-name"]
    },
    "mcpServers": [
      {
        "name": "filesystem",
        "command": "npx",
        "args": [
          "@modelcontextprotocol/server-filesystem",
          "./"
        ]
      }
    ]
  }
}

Edit notes:

Replace YOUR_API_KEY with your secure key (do not commit to public repos).
Replace model-name with the model(s) you plan to use or list several.

`.nanocoder/commands/test.md`

---
description: "Generate comprehensive unit tests for the specified component"
aliases: ["testing", "spec"]
parameters:
  - name: "component"
    description: "The component or function to test"
    required: true
  - name: "language"
    description: "Testing language or framework (optional)"
    required: false
---

Generate comprehensive unit tests for {{component}}. Include:
- Happy path scenarios
- Edge cases and error handling
- Mock dependencies where appropriate
- Clear test descriptions and example assertions
- If language is provided, format examples for {{language}}

`.nanocoder/commands/review.md`

---
description: "Perform a code review for the specified file or module"
parameters:
  - name: "path"
    description: "Relative path to the file or module to review"
    required: true
---

Please review the file at {{path}} for correctness, readability, edge cases, performance, and security issues. Provide:
- A short executive summary
- A prioritized list of issues (critical / major / minor)
- Suggested code changes, including examples or diffs

Place these files under .nanocoder/commands/ and run them with /test or /review.

11 — Practical checklist and deployment plan

Follow this stepwise plan to adopt Nanocoder safely and effectively.

Pilot phase (1–2 days)

[ ] Install Nanocoder globally on one developer machine.
[ ] Create a small demo repo and add agents.config.json with a filesystem MCP pointing to the demo repo.
[ ] Add one or two command templates (test.md, review.md).
[ ] Run local tests and evaluate results.

Team adoption (1–2 weeks)

[ ] Create a shared pattern for command templates (naming, parameters, descriptions).
[ ] Decide where secret keys live and how to distribute them (avoid committing them).
[ ] Create a policy for MCP permissions and audit logging.
[ ] Hold a short workshop showing how to author commands and interpret results.

Production rollout (ongoing)

[ ] Add agents.config.json to selected production repositories with appropriate scoping.
[ ] Periodically review MCP logs and command template usage.
[ ] Update templates and provider configurations as the team learns and needs change.

12 — FAQ and troubleshooting tips

Q: Where does Nanocoder save user preferences?
A: Preferences are stored in a user config file in the home directory (for example ~/.nanocoder-preferences.json). Delete or edit it to reset preferences.

Q: How do I change provider or model at runtime?
A: Use the built-in /provider and /model commands inside the Nanocoder CLI to switch. The CLI shows available providers and models based on your agents.config.json and what the provider exposes.

Q: Can I use Nanocoder in CI?
A: The architecture is TypeScript-first and developer-friendly, so in theory you can run Nanocoder commands in automation. Do so only after ensuring secrets and MCP permissions are safe for an automated environment.

Troubleshooting checklist

Ensure Node.js 18+ is installed.
Confirm agents.config.json is valid JSON at the repo root.
If MCP servers fail to start, run their command manually to check errors and environment variables.
Use /debug or run in developer mode to get verbose logs if behavior is unexpected.

13 — Conclusion — next steps and a practical 7-day plan

This section converts the guidance above into an actionable week-long plan you can follow.

Day 1 — Setup and exploration

Install Nanocoder locally and run it in a demo repo.
Create a filesystem MCP pointing to that demo.
Add test.md and review.md commands and exercise them.

Day 2 — Authoring templates

Draft 5 command templates your team will reuse (e.g., code review, unit tests, changelog draft, release checklist, dependency audit).
Share templates in a documentation folder for review.

Day 3 — Access and security

Decide how you will store provider keys (local env vars, secret manager).
Lock MCP scopes to minimal paths and enable logging if possible.

Day 4 — Team workshop

Run a short internal session showing how to use Nanocoder and how to write templates.
Collect feedback on useful templates.

Day 5–7 — Pilot with a production repo

Test Nanocoder in one real repository with human review steps before applying any automated writes.
Iterate templates based on developer feedback and observed behavior.

If you follow this 7-day plan you will arrive at a measured adoption path that balances velocity and safety. All template formats, configuration examples, and command patterns referenced in this plan are derived from the README material you provided.

Images you can use for blog illustration

Use free, no-attribution (or permissive) images related to developer workspaces and terminals. Example searches and sites:

Unsplash: search coding terminal, developer workspace.
Example image: https://images.unsplash.com/photo-1518770660439-4636190af475
Pexels: search programming, team coding.
Example image: https://images.pexels.com/photos/1181675/pexels-photo-1181675.jpeg

Place images near the installation and workflow sections to make the article approachable.

Closing summary (concise and actionable)

Nanocoder converts recurring AI prompt work into project-scoped developer tools. By using project configuration, MCP servers, and simple markdown command templates, teams can get repeatable assistance (code reviews, test generation, migration plans) while keeping control over data and tool permissions. Start small: run the local demo, create a few command templates, and then expand provider and MCP usage with a careful security policy. The templates and configuration examples in this guide are directly usable in your repository.

Nanocoder: Mastering Local-First Command-Line Coding Assistant Workflows [2024 Guide]