@motesoftware/nanocoder
Advanced tools
A local-first CLI coding agent that brings the power of agentic coding tools like Claude Code and Gemini CLI to local models or controlled APIs like OpenRouter
A local-first CLI coding agent that brings the power of agentic coding tools like Claude Code and Gemini CLI to local models or controlled APIs like OpenRouter. Built with privacy and control in mind, Nanocoder supports multiple AI providers with tool support for file operations and command execution.
Nanocoder is a local-first CLI coding agent that brings the power of agentic coding tools like Claude Code and Gemini CLI to local models or controlled APIs like OpenRouter. Built with privacy and control in mind, Nanocoder supports any AI provider that has an OpenAI compatible end-point, tool and non-tool calling models.
This comes down to philosophy. OpenCode is a great tool, but it's owned and managed by a venture-backed company that restricts community and open-source involvement to the outskirts. With Nanocoder, the focus is on building a true community-led project where anyone can contribute openly and directly. We believe AI is too powerful to be in the hands of big corporations and everyone should have access to it.
We also strongly believe in the "local-first" approach, where your data, models, and processing stay on your machine whenever possible to ensure maximum privacy and user control. Beyond that, we're actively pushing to develop advancements and frameworks for small, local models to be effective at coding locally.
Not everyone will agree with this philosophy, and that's okay. We believe in fostering an inclusive community that's focused on open collaboration and privacy-first AI coding tools.
Firstly, we would love for you to be involved. You can get started contributing to Nanocoder in several ways, check out the Community section of this README.
Install globally and use anywhere:
npm install -g @motesoftware/nanocoder
Then run in any directory:
nanocoder
If you want to contribute or modify Nanocoder:
Prerequisites:
Setup:
git clone [repo-url]
cd nanocoder
npm install
npm run build
npm run start
Or build and run in one command:
npm run dev
Nanocoder supports any OpenAI-compatible API through a unified provider configuration. Create agents.config.json in your working directory (where you run nanocoder):
{
"nanocoder": {
"providers": [
{
"name": "Ollama",
"baseUrl": "http://localhost:11434/v1",
"models": ["qwen2.5-coder:14b", "llama3.2"]
},
{
"name": "OpenRouter",
"baseUrl": "https://openrouter.ai/api/v1",
"apiKey": "your-openrouter-api-key",
"models": ["openai/gpt-4o-mini", "anthropic/claude-3-haiku"]
},
{
"name": "LM Studio",
"baseUrl": "http://localhost:1234/v1",
"models": ["local-model"]
}
]
}
}
Common Provider Examples:
Ollama (Local):
ollama pull qwen2.5-coder:14b"baseUrl": "http://localhost:11434/v1"OpenRouter (Cloud):
"baseUrl": "https://openrouter.ai/api/v1""apiKey": "your-api-key"LM Studio: "baseUrl": "http://localhost:1234/v1"
vLLM: "baseUrl": "http://localhost:8000/v1"
LocalAI: "baseUrl": "http://localhost:8080/v1"
llama.cpp server: "baseUrl": "http://localhost:8080/v1"
OpenAI: "baseUrl": "https://api.openai.com/v1"
Provider Configuration:
name: Display name used in /provider commandbaseUrl: OpenAI-compatible API endpointapiKey: API key (optional for local servers)models: Available model list for /model commandNanocoder supports connecting to MCP servers to extend its capabilities with additional tools. Configure MCP servers in your agents.config.json:
{
"nanocoder": {
"mcpServers": [
{
"name": "filesystem",
"command": "npx",
"args": [
"@modelcontextprotocol/server-filesystem",
"/path/to/allowed/directory"
]
},
{
"name": "github",
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "your-github-token"
}
},
{
"name": "custom-server",
"command": "python",
"args": ["path/to/server.py"],
"env": {
"API_KEY": "your-api-key"
}
}
]
}
}
When MCP servers are configured, Nanocoder will:
/mcp commandPopular MCP servers:
Note: The
agents.config.jsonfile should be placed in the directory where you run Nanocoder, allowing for project-by-project configuration with different models or API keys per repository.
Nanocoder automatically saves your preferences to remember your choices across sessions. Preferences are stored in ~/.nanocoder-preferences.json in your home directory.
What gets saved automatically:
How it works:
/provider, your choice is saved/model, the selection is saved for that specific providerManual management:
~/.nanocoder-preferences.json to start fresh/provider and /model commands instead/help - Show available commands/clear - Clear chat history/model - Switch between available models/provider - Switch between configured AI providers/mcp - Show connected MCP servers and their tools/debug - Toggle logging levels (silent/normal/verbose)/custom-commands - List all custom commands/exit - Exit the application!command - Execute bash commands directly without leaving Nanocoder (output becomes context for the LLM)Nanocoder supports custom commands defined as markdown files in the .nanocoder/commands directory. Like agents.config.json, this directory is created per codebase, allowing you to create reusable prompts with parameters and organize them by category specific to each project.
Example custom command (.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
---
Generate comprehensive unit tests for {{component}}. Include:
- Happy path scenarios
- Edge cases and error handling
- Mock dependencies where appropriate
- Clear test descriptions
Usage: /test component="UserService"
Features:
{{parameter}} syntax/refactor:dry)Pre-installed Commands:
/test - Generate comprehensive unit tests for components/review - Perform thorough code reviews with suggestions/refactor:dry - Apply DRY (Don't Repeat Yourself) principle/refactor:solid - Apply SOLID design principles.nanocoder/commands/{{parameter}} syntax for dynamic contentrefactor/dry.md)/historyagents.config.jsonWe're a small team building Nanocoder and would love your help! Whether you're interested in contributing code, documentation, or just being part of our community, there are several ways to get involved.
If you want to contribute:
If you want to be part of our community:
Whether you're interested in:
All contributions and community participation are welcome!
This is a test line.
FAQs
A local-first CLI coding agent that brings the power of agentic coding tools like Claude Code and Gemini CLI to local models or controlled APIs like OpenRouter
The npm package @motesoftware/nanocoder receives a total of 5 weekly downloads. As such, @motesoftware/nanocoder popularity was classified as not popular.
We found that @motesoftware/nanocoder demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub Actions checkout now blocks risky pull_request_target checkouts by default to help prevent pwn request supply chain attacks.
Product
Socket now supports Custom Roles and Repository Access Permissions so organizations can control who can access specific repositories and actions.
Product
Socket MCP now lets AI assistants review org alerts, investigate threats using the Socket threat feed, and inspect package files in addition to dependency scoring.