DOCSEARCHbyAlgolia
Submit Docs

Nanocoder Documentation

repository·main·Indexed 25 days ago

https://github.com/nano-collective/nanocoder

An open-source, privacy-first terminal coding agent built by the Nano Collective. Nanocoder allows developers to use local models (via Ollama, llama.cpp, LM Studio, etc.) or remote OpenAI-compatible APIs to perform agentic coding tasks. Key features include a VS Code extension with sidebar chat and diff previews, support for the Agent Client Protocol (ACP) and Model Context Protocol (MCP), a per-project daemon for event-driven Skills, and extensive provider support including Anthropic, Google Gemini, and OpenRouter.

Tokens
63.7K
Snippets
153
Records
410
Agent score
81%

What's inside Nanocoder

  1. Overview of Nanocoder capabilities

    main

    Nanocoder is a community-driven, privacy-respecting, and local-first terminal agent. Key features include:

    • Broad Provider Support: 20+ providers including Anthropic, Google, OpenAI, OpenRouter, Copilot, and more.
    • Robust Tool Calling: Supports native function calling, XML fallback, and JSON fallback with automatic malformed-output repair.
    • Advanced Workflow Tools: Includes checkpointing (snapshot/restore), context compression, session autosave/resume, and task management.
    • Runtime Tuning: Ability to change tool profiles, compaction strategies, and model parameters live during a session.
    • VS Code Integration: A companion extension providing live diff previews of agent edits.

  3. Adhere to Nanocoder constraints for tool usage and formatting

    main

    When interacting with or extending Nanocoder, follow these operational constraints to ensure compatibility and reliability:

    File Editing

    • Use dedicated tools: Do not use bash for file edits. Always use the appropriate file-editing tools provided by the environment.
    • Read before editing: Always perform a read operation on a file before attempting to modify it.

    Bash Command Usage

    • OS/Shell awareness: Tailor all bash commands to the specific operating system and shell of the user.
    • Avoid shell expansions: Do not use ~ or $HOME in bash commands; use absolute paths or environment-specific variables as required by the environment.

    Verification and Output

    • Verify outcomes: Use tools to verify the results of an action rather than making assumptions about success.
    • No markdown tables: NEVER use markdown tables in output; use bulleted lists or short prose instead.

  4. Use Agent Client Protocol (ACP) for editor integration

    main

    Nanocoder can run as an Agent Client Protocol (ACP) server, allowing ACP-compatible editors (like Zed) to drive Nanocoder as a native coding agent. In this mode, Nanocoder operates headlessly via JSON-RPC over stdin/stdout, and the editor takes over the UI responsibilities, including rendering streaming text, tool cards, diffs, and permission prompts.

    Comparison: ACP vs. VS Code Extension

    FeatureACPVS Code Extension
    TransportJSON-RPC over stdin/stdoutWebSocket
    Flag--acp--vscode
    Primary EditorsZed and other ACP clientsVS Code
    UI OwnershipThe editor is the UI (headless agent)Nanocoder terminal UI stays in charge

    Supported ACP Features

    • Streaming responses: Reasoning and thinking are rendered in the editor's agent panel.
    • Tool calls: File tools report metadata; edits (string_replace, write_file) include before/after diff previews.
    • Permission prompts: Tool approvals surface as native editor prompts, respecting current development modes.
    • Development modes: normal, auto-accept, yolo, and plan are selectable from the editor (sessions default to auto-accept).
    • Model management: View and switch models via the editor's UI.
    • ask_user: Clarifying questions appear as selectable buttons (note: free-form text input is not supported over ACP).
    • File referencing: Using the editor's @-mention UI includes the file's live buffer (including unsaved edits) in the prompt.
    • Session reload: Reopening threads is supported.
    nanocoder --acp

  5. Operational constraints for Nanocoder

    main

    When interacting with Nanocoder, be aware of the following operational constraints and best practices for environment management, file operations, and command execution:

    Environment & Directory Management

    • Fixed Working Directory: Nanocoder operates within a fixed working directory. It does not support shell expansions like ~ or $HOME for path resolution.
    • One-off Directory Changes: To execute a command in a different directory, use the pattern: cd /path && command.

    File Operations

    • Tool Usage: Always use dedicated file manipulation tools rather than raw bash commands for file operations.
    • Workflow: Always read a file before attempting to edit it. Be mindful that auto-formatting may occur during or after edits.

    Command Execution

    • OS/Shell Awareness: Commands should be tailored to the user's specific operating system and shell environment.
    • Safety & Clarity: Avoid unsafe commands. Always provide an explanation of what a command does before execution.

    Error Handling & Completion

    • Error Assumption: If a tool execution does not return an error, assume success.
    • Failure Investigation: If a command fails, investigate the cause using available tools rather than making assumptions.
    • Verification: Verify results using tools instead of relying on inferred state.
    • Systematic Workflow: Work systematically by continuing with tools, presenting final results, and minimizing unnecessary conversational filler.

  6. Use resources for command context

    main

    When using the directory-as-command pattern, you can bundle additional context (like templates, configs, or reference docs) by placing them in a resources/ subdirectory. Files in this directory are automatically loaded and passed as additional context to the command.

    Directory Structure

    .nanocoder/commands/
  api-gen/
    api-gen.md            <-- The command (must match directory name)
    resources/
      template.yaml       <-- Loaded as a resource
      examples.json       <-- Loaded as a resource

  8. Configure Tool Profiles for different model sizes

    main

    Tool profiles control which tools the AI can access, helping to manage prompt size and model capability. The auto profile is the default and resolves based on the model's size hint.

    ProfileToolsBehavior
    auto (default)Resolves to full, minimal, or nanoCloud/unknown models get full; models up to 15B $\rightarrow$ minimal; models up to 4B $\rightarrow$ nano
    fullAll registered tools including MCP serversNo filtering applied
    minimal8 core tools (read_file, write_file, string_replace, execute_bash, find_files, search_file_contents, list_directory, agent)Slim prompt and single-tool enforcement
    nano5 core tools (read_file, string_replace, write_file, execute_bash, search_file_contents)Ultra-slim prompt, single-tool enforcement, AGENTS.md omitted by default

    Note on MCP Tools: MCP tools are only exposed in the full profile. If your MCP tools are missing, switch to the full profile or use a larger/cloud model.

  9. Use XML-based tool calling for models without native support

    main

    When using a model that does not support native tool calling, you must use a specific XML format to trigger tool execution. The model outputs an XML block where the outer tag is the tool name and inner tags represent the parameters.

    Format Requirements:

    • The outer XML tag must be the exact tool_name.
    • Each parameter must be wrapped in its own XML tag inside the tool block.
    • Do NOT use attributes (e.g., avoid <tool name="..." or <param name="...").

    Operational Rules:

    • Verify all required parameters before calling a tool; never use placeholder values.
    • You may call multiple tools in sequence.
    • Describe actions naturally (e.g., "editing file" instead of "using edit tool").
    • Never assume success; verify the outcome of each step.

    Execution Flow: After a tool is called, immediately proceed to the next step in your reasoning chain. Do not wait for user input, as tool execution is considered ongoing work.

    <tool_name>
<param1>value1</param1>
<param2>value2</param2>
</tool_name>

  10. Use environment variable substitution in config

    main

    You can use environment variables inside your agents.config.json to avoid hardcoding sensitive information like API keys. Supported syntaxes:

    • $VAR_NAME: Simple reference
    • ${VAR_NAME}: Braced reference
    • ${VAR_NAME:-default}: Reference with a default value
    {
	"name": "OpenRouter",
	"baseUrl": "https://openrouter.ai/api/v1",
	"apiKey": "${OPENROUTER_API_KEY}",
	"models": ["your-model-name"]
}

  11. How subagents work in Nanocoder

    main

    A subagent is a specialized AI agent that the main agent can delegate tasks to using the agent tool. Subagents run in isolated conversations with their own system prompts, filtered tools, and optionally different models or providers. This isolation keeps the main conversation's context window clean by only returning the final result to the main agent.

    Parallel Execution

    The main agent can call the agent tool multiple times in a single response to execute tasks in parallel.

    • Concurrency Limit: A maximum of 5 agents can run concurrently.
    • Error Handling: If you exceed 5 concurrent calls, the excess calls will receive an error and must be retried.
    Tools: read_file, search_file_contents, find_files, list_directory, 
       lsp_get_diagnostics, git_status, git_log, git_diff

  12. How to use the agent tool for subagent delegation

    main

    The agent tool allows you to delegate tasks to subagents that operate in isolated contexts. Subagents do not consume your main context window for their intermediate steps (file reads, searches, or tool outputs); they only return the final result to you.

    Best Practices for Delegation:

    • Default to delegating: If a task requires 2 or more tool calls, use the agent tool. Reserve direct tool calls only for single-shot operations on targets already named by the user (e.g., reading one known path or editing one file already in context).
    • Launch in parallel: When facing multiple independent tasks or questions, call the agent tool multiple times within a single response. These calls run concurrently, making parallel delegation more efficient than sequential execution.

    When to delegate instead of handling inline:

    • Exploring unfamiliar code, tracing call sites, or understanding architecture.
    • Searching for patterns, usages, or implementations across the codebase.
    • Reviewing changes, diffs, or PRs.
    • Multi-step refactors that require reading several files first.
    • Any task where you need to 'look around' before providing a definitive answer.