nanocoder

Nanocoder implements a client-factory pattern (source/client-factory.ts) that abstracts multiple LLM providers (Ollama, LM Studio, OpenRouter, OpenAI, Anthropic) behind a unified interface. The factory detects provider type from configuration, instantiates the appropriate client, and routes all chat completions through a standardized handler that normalizes streaming responses and function-calling schemas across providers. This enables seamless switching between local and cloud models without code changes.

Nanocoder implements a risk-and-approval system that intercepts tool calls (file operations, bash commands, web fetches) before execution, displays the intended action to the user with context, and requires explicit approval before proceeding. The system categorizes operations by risk level (read-only vs destructive), shows diffs for file modifications, and logs all executed actions for audit trails. This is enforced through a middleware layer in the tool execution flow that blocks execution until user confirmation is received.

Nanocoder provides a set of built-in tools that the agent can invoke: file read/write/delete operations, bash command execution with output capture, and HTTP web fetching. Each tool is implemented as a function that validates inputs, executes the operation, and returns results or errors. Tools are registered in a tool registry and exposed to the LLM via function-calling schemas. All tool invocations go through the approval system before execution.

Nanocoder maintains application state through React hooks (useAppInitialization, custom hooks) that manage conversation history, configuration state, and tool execution state. Conversation history is stored in memory as an array of messages with roles and content. Session state persists for the duration of the CLI session but is lost on exit. The system uses React's state management patterns to ensure UI updates reflect state changes in real-time.

Nanocoder implements a structured application lifecycle (source/hooks/useAppInitialization.tsx) with distinct initialization phases: configuration loading, client creation, tool system setup, and external integrations. Each phase reports progress asynchronously and failures in later phases don't prevent application startup. The system uses async/await patterns to manage dependencies between phases and provides error handling that allows partial initialization. The UI displays initialization progress to the user.

Nanocoder integrates with the Model Context Protocol to dynamically load and execute tools from external MCP servers. The system maintains a registry of MCP server configurations, establishes connections at startup, discovers available tools from each server, and routes tool invocations through the MCP protocol. This allows users to extend the agent's capabilities by adding custom MCP servers without modifying the core codebase. Tool discovery, schema validation, and execution are handled through the MCP client library.

Nanocoder automatically analyzes the project structure at startup, tags files by type/purpose (source code, tests, config, docs), and integrates git history to understand recent changes and file ownership. This context is maintained in memory and used to prioritize which files to include in LLM prompts, reducing token usage and improving relevance. The system uses file extension matching, directory patterns, and git blame/log data to build a semantic understanding of the codebase without requiring manual configuration.

Nanocoder supports defining reusable prompts as markdown files with template variables (e.g., {{filename}}, {{language}}) that are substituted at runtime. Users can create custom commands that encapsulate multi-step workflows (e.g., 'refactor-function', 'add-tests') as markdown templates, invoke them via CLI, and pass parameters that are interpolated into the prompt. The command system integrates with the chat handler to execute the resulting prompt as a normal agent interaction.

Nanocoder builds its UI using the Ink framework (React for terminals), rendering an interactive terminal interface with real-time streaming message display, user input handling with autocomplete suggestions, and status indicators. The UI layer (App.tsx, UserInput.tsx, ChatQueue.tsx components) manages message queuing, renders streaming responses character-by-character, and provides keyboard-driven navigation. The system maintains a message history and renders it incrementally as the agent responds, providing immediate visual feedback.

Nanocoder provides a VS Code extension that integrates with the CLI agent, enabling users to invoke the agent from within the editor and see results (diffs, diagnostics, suggestions) directly in the editor UI. The extension communicates with the nanocoder CLI via IPC or network, sends file context and user requests, and renders responses as inline diffs, code actions, and diagnostic markers. This bridges the terminal-based agent with the GUI editor workflow.

Nanocoder supports a non-interactive mode where it reads prompts from stdin or files, executes them without requiring user approval, and outputs results to stdout/files. This mode disables the approval workflow, removes interactive UI elements, and formats output for machine consumption (JSON, plain text). The mode is triggered via CLI flags and is designed for integration into CI/CD pipelines, automated testing, and batch processing workflows.

Nanocoder implements a configuration system (source/config/index.ts, source/config/preferences.ts) that manages LLM provider settings, tool configurations, and user preferences. The system includes an interactive configuration wizard that guides users through setup, auto-detects available providers (Ollama, LM Studio, OpenAI), and validates configurations before saving. Configuration is stored in a standard format (YAML/JSON) and can be edited manually or through the wizard. The system supports project-specific overrides and global defaults.

Nanocoder implements a prompt system that formats user messages with role information (user, assistant, system), injects project context (file tags, git history), and manages conversation history. The system constructs prompts by combining user input with automatically-discovered context, formats them according to the LLM provider's requirements, and maintains a conversation history for multi-turn interactions. System prompts define the agent's behavior and capabilities.