@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.
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!
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.