### Install and Serve vLLM

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/configuration/providers/vllm.md

Install the vLLM library and start the OpenAI-compatible API server. Replace 'model-name' with your actual model.

```bash
pip install vllm
vllm serve model-name --port 8000
```

--------------------------------

### Setup Nanocoder Development Environment

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/getting-started/installation.md

Clone the repository, install dependencies using pnpm, and build the project for development.

```bash
git clone [repo-url]
cd nanocoder
pnpm install
```

--------------------------------

### Example Full Configuration File

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/configuration.md

A comprehensive example of a Nanocoder configuration file, including provider settings, permissions, and modes.

```json
{
  "nanocoder": {
    "providers": [
      {
        "name": "OpenRouter",
        "type": "openrouter",
        "baseUrl": "https://openrouter.ai/api/v1",
        "apiKey": "${OPENROUTER_API_KEY}",
        "models": [
          "google/gemini-3.1-flash",
          "anthropic/claude-opus-4"
        ],
        "requestTimeout": 30000,
        "maxRetries": 2
      },
      {
        "name": "Local Ollama",
        "type": "ollama",
        "baseUrl": "http://localhost:11434/v1",
        "models": ["llama3.1:70b", "neural-chat:7b"],
        "requestTimeout": 300000,
        "socketTimeout": 5000
      }
    ],
    "alwaysAllow": ["read_file", "list_directory"],
    "disabledTools": ["execute_bash"],
    "defaultMode": "auto-accept",
    "autoCompact": {
      "enabled": true,
      "threshold": 60,
      "mode": "conservative",
      "strategy": "llm"
    },
    "systemPrompt": {
      "mode": "append",
      "content": "Prioritize clarity and correctness."
    }
  }
}
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/nano-collective/nanocoder/blob/main/CONTRIBUTING.md

Install all necessary project dependencies using pnpm. This command should be run after cloning the repository.

```bash
pnpm install
```

--------------------------------

### Start the Application

Source: https://github.com/nano-collective/nanocoder/blob/main/CONTRIBUTING.md

Run the Nanocoder application. This command is useful for testing your setup or running the application in a development environment.

```bash
pnpm run start
```

--------------------------------

### Install and Run MLX Server

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/configuration/providers/mlx-server.md

Install the MLX-LM package using pip and then run the MLX Server from the command line, specifying the model to serve. This command starts the server with an OpenAI-compatible API.

```bash
pip install mlx-lm
mlx_lm.server --model mlx-community/model-name
```

--------------------------------

### Docker Setup for Nanocoder

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/cli-interface.md

Set up a Docker environment for Nanocoder, including global installation and setting the OpenRouter API key. The entrypoint runs Nanocoder in plain mode.

```dockerfile
FROM node:22-alpine
RUN npm install -g @nanocollective/nanocoder
ENV OPENROUTER_API_KEY=sk-...
ENTRYPOINT ["nanocoder", "--plain", "run"]
```

```bash
docker run myapp "analyze /data/code"
```

--------------------------------

### System Prompt Configuration Example

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/configuration.md

Example JSON configuration for appending a custom system prompt message to Nanocoder's behavior.

```json
{
  "nanocoder": {
    "systemPrompt": {
      "mode": "append",
      "content": "Always explain your reasoning in detail."
    }
  }
}
```

--------------------------------

### Start Application

Source: https://github.com/nano-collective/nanocoder/blob/main/AGENTS.md

Run the compiled application.

```bash
npm run start
```

--------------------------------

### Checkpointing Workflow Example

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/checkpointing.md

This example demonstrates a typical workflow for using checkpoints to save, revert, and compare different states of a project during AI-assisted development.

```bash
# Save current state before trying something new
/checkpoint create before-refactor

# Ask the AI to try an approach...
# If it doesn't work out:
/checkpoint load before-refactor

# If it went well, save the new state:
/checkpoint create after-refactor

# Compare what you have:
/checkpoint list
```

--------------------------------

### Start llama.cpp Server

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/configuration/providers/llama-cpp.md

Start the llama.cpp server with a specified model. This command is necessary before configuring Nanocoder to use it as a provider.

```bash
llama-server -m model.gguf --port 8080
```

--------------------------------

### Start Nanocoder Daemon

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/scheduler.md

Command to start the Nanocoder daemon, which will pick up new skill subscriptions.

```bash
nanocoder daemon start
```

--------------------------------

### Example Configuration with Environment Variable

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/configuration.md

Shows how to use environment variable substitution for an API key in the configuration.

```json
{
  "nanocoder": {
    "providers": [
      {
        "name": "OpenRouter",
        "config": {
          "apiKey": "${OPENROUTER_API_KEY:-}"
        }
      }
    ]
  }
}
```

--------------------------------

### Nanocoder Help Output Example

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/cli-interface.md

An example of the output generated when requesting help from the Nanocoder CLI, detailing usage, commands, and options.

```bash
Usage: nanocoder [options] [command]

Commands:
  copilot login [provider-name]   Log in to GitHub Copilot
  daemon <subcommand>             Manage the per-project skill daemon

Options:
  -v, --version                   Show version number
  -h, --help                       Show help
  --provider                       Specify AI provider
  --model                          Specify AI model
  --mode                           Start in specific development mode
  ...
```

--------------------------------

### AutoCompact Configuration Example

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/configuration.md

Example JSON configuration for enabling and setting parameters for Nanocoder's auto-context compaction feature.

```json
{
  "nanocoder": {
    "autoCompact": {
      "enabled": true,
      "threshold": 60,
      "mode": "conservative",
      "strategy": "llm",
      "notifyUser": true
    }
  }
}
```

--------------------------------

### VS Code Settings Example

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/vscode-extension.md

Configure Nanocoder extension settings in your VS Code settings.json file. This example shows how to enable auto-connect, set the server port, and enable diff preview.

```json
{
	"nanocoder.autoConnect": true,
	"nanocoder.serverPort": 51820,
	"nanocoder.showDiffPreview": true
}
```

--------------------------------

### Start llama.cpp Server with Custom Context Size

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/configuration/providers/llama-cpp.md

Start the llama.cpp server with a custom context size. Adjust --ctx-size based on your system's memory to handle larger contexts.

```bash
llama-server -m model.gguf --ctx-size 32768
```

--------------------------------

### Install Nanocoder Globally

Source: https://github.com/nano-collective/nanocoder/blob/main/README.md

Install Nanocoder using npm. This command makes the nanocoder CLI available system-wide.

```bash
npm install -g @nanocollective/nanocoder
nanocoder
```

--------------------------------

### Message Usage Examples

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/types.md

Illustrates how to create user and assistant messages. The assistant message example shows how to include tool calls.

```typescript
const userMessage: Message = {
  role: 'user',
  content: 'Analyze the error in this file'
};

const assistantMessage: Message = {
  role: 'assistant',
  content: 'I found the issue...', 
  tool_calls: [{
    id: 'call-123',
    function: {
      name: 'read_file',
      arguments: {path: 'src/app.ts'}
    }
  }]
};
```

--------------------------------

### File Explorer Workflow Example

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/file-explorer.md

Demonstrates a typical workflow for using the file explorer, including opening, navigating, selecting files, searching, and exiting to add selections to the input.

```bash
# Open the file explorer
/explorer

# Navigate to src/components, expand it with Enter
# Select the files you need with Space
# Use / to search for a specific file if the tree is large
# Press Esc — selected files are added to your input as @file mentions
# Type your question and press Enter
```

--------------------------------

### Install Nanocoder via Homebrew

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/getting-started/installation.md

After tapping the repository, use this command to install Nanocoder using Homebrew. This is suitable for macOS and Linux users.

```bash
brew install nanocoder
```

--------------------------------

### Nanocoder Run Command Examples

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/cli-interface.md

Illustrative examples of using the `nanocoder run` command with various options, including simple prompts, provider/model overrides, development modes, context limits, and plain mode.

```bash
# Simple prompt
nanocoder run "count lines in src/"
```

```bash
# With provider/model override
nanocoder --provider openrouter --model google/gemini-3.1-flash run "analyze code"
```

```bash
# Non-interactive with auto-accept
nanocoder --mode auto-accept run "fix linting errors"
```

```bash
# Planning mode (don't execute)
nanocoder --mode plan run "what changes needed?"
```

```bash
# With context limit
nanocoder --context-max 64k run "summarize README.md"
```

```bash
# Plain (lightweight) mode
nanocoder --plain run "quick check"
```

```bash
# Trust directory (skip prompt)
nanocoder --trust-directory run "analyze files"
```

--------------------------------

### Legacy Schedules JSON Example

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/scheduler.md

This is an example of the old .nanocoder/schedules.json format for defining scheduled tasks.

```json
// .nanocoder/schedules.json
[{"cron": "0 9 * * MON", "command": "/weekly-report"}]
```

--------------------------------

### Install Extension VSIX from npm Global Install

Source: https://github.com/nano-collective/nanocoder/blob/main/plugins/vscode/README.md

Locate and install the Nanocoder VS Code extension VSIX file from its bundled location after a global npm installation.

```bash
code --install-extension $(npm root -g)/@nanocollective/nanocoder/assets/nanocoder-vscode.vsix
```

--------------------------------

### Start Nanocoder with Specific Provider

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/getting-started/index.md

Launch Nanocoder interactive mode specifying the AI provider to use.

```bash
nanocoder --provider ollama
```

--------------------------------

### AISDKClient Constructor

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/ai-sdk-client.md

Initializes the AISDKClient. Use the static `create()` method for asynchronous setup.

```APIDOC
## Constructor AISDKClient

### Description
Initializes the AISDKClient with provider configuration. Note: Use the `create()` factory method for asynchronous initialization.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **providerConfig** (`AIProviderConfig`) - Required - Provider configuration including models, baseURL, API key, timeouts
```

--------------------------------

### Start Nanocoder with Specific Provider and Model

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/getting-started/index.md

Launch Nanocoder interactive mode specifying both the AI provider and the model.

```bash
nanocoder --provider openrouter --model google/gemini-3.1-flash
```

--------------------------------

### LlamaTokenizer Examples

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/tokenization-api.md

Examples of using `LlamaTokenizer` for accurate token counting with various open-source models. Falls back to character estimation if unavailable.

```typescript
const tokenizer = createTokenizer('ollama', 'llama3.1:70b');
const count = tokenizer.countTokens('The quick brown fox');

const mistral = createTokenizer('ollama', 'mistral:7b');
const tokens = mistral.countTokens('Your text here');
```

--------------------------------

### CLI Integration Setup

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/app-component.md

Sets up the main App component for CLI execution, passing various arguments and flags to configure its behavior. This is the entry point for command-line usage.

```typescript
import {App} from '@nanocollective/nanocoder';

const {default: App} = await import('@/app/index.ts');

const props: AppProps = {
  nonInteractiveMode: args.includes('run'),
  nonInteractivePrompt: extractPrompt(args),
  cliProvider: extractFlag(args, '--provider'),
  cliModel: extractFlag(args, '--model'),
  cliMode: extractFlag(args, '--mode') as CliMode,
  vscodeMode: args.includes('--vscode'),
  vscodePort: extractNumber(args, '--vscode-port'),
  trustDirectory: args.includes('--trust-directory'),
};

render(<App {...props} />);
```
```

--------------------------------

### MCP Server Configuration Example

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/configuration/mcp-configuration.md

Defines various MCP servers including filesystem, GitHub, and a Context7 server. Use this to set up project-specific servers that can be shared via version control.

```json
{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"],
      "alwaysAllow": ["list_directory", "read_file"]
    },
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    },
    "context7": {
      "transport": "http",
      "url": "https://mcp.context7.com/mcp",
      "timeout": 30000
    }
  }
}
```

--------------------------------

### Custom Tool File Structure Example

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/custom-tools.md

Illustrates the directory structure for custom tools, showing how markdown files in the .nanocoder/tools/ directory map to tool names.

```shell
.nanocoder/tools/
  k8s-pods.md         -> k8s_pods
  jira-ticket.md      -> jira_ticket
```

--------------------------------

### Install Biome VS Code Extension via CLI

Source: https://github.com/nano-collective/nanocoder/blob/main/CONTRIBUTING.md

Installs the Biome VS Code extension directly from the command line.

```bash
code --install-extension biomejs.biome
```

--------------------------------

### Build the Project

Source: https://github.com/nano-collective/nanocoder/blob/main/CONTRIBUTING.md

Compile and build the Nanocoder project. This step is necessary after installing dependencies or making code changes.

```bash
pnpm run build
```

--------------------------------

### Chat with LLM and Stream Tokens

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/README.md

This example demonstrates how to initiate a chat with an LLM, stream tokens as they are received, and process the final response.

```typescript
import {AISDKClient} from '@nanocollective/nanocoder';
import type {Message} from '@nanocollective/nanocoder';

const client = await AISDKClient.create(config);

const messages: Message[] = [
  {role: 'user', content: 'What is 2+2?'},
];

const response = await client.chat(messages, {}, {
  onToken: (token) => process.stdout.write(token),
  onFinish: () => console.log('\n[Done]')
});

console.log(`Status: ${response.choices[0].message.content}`);
```

--------------------------------

### llama-swap Configuration

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/configuration/providers/llama-swap.md

Configure llama-swap with its name, base URL, and the models it should serve. No API key is needed for local setups.

```json
{
	"name": "llama-swap",
	"baseUrl": "http://localhost:9292/v1",
	"models": ["model-1", "model-2"]
}
```

--------------------------------

### Configure Nanocoder Providers

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/README.md

Example configuration file for Nanocoder, specifying providers like OpenRouter with API keys and model lists.

```json
{
  "nanocoder": {
    "providers": [
      {
        "name": "OpenRouter",
        "baseUrl": "https://openrouter.ai/api/v1",
        "apiKey": "$OPENROUTER_API_KEY",
        "models": ["google/gemini-3.1-flash", "anthropic/claude-opus-4"]
      }
    ]
  }
}
```

--------------------------------

### Parse and Execute Tools Example

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/tool-calling-api.md

An asynchronous function demonstrating how to parse tool calls from a model response and execute corresponding handlers.

```typescript
import {parseToolCalls} from '@nanocollective/nanocoder';

async function handleFallbackToolCalls(
  modelResponse: string,
  toolHandlers: Record<string, (args: any) => Promise<string>>,
): Promise<string[]> {
  const result = parseToolCalls(modelResponse);
  
  if (!result.success) {
    throw new Error(`Failed to parse tool calls: ${result.error}`);
  }
  
  const outputs: string[] = [];
  
  for (const call of result.toolCalls) {
    const handler = toolHandlers[call.function.name];
    if (!handler) {
      outputs.push(`Unknown tool: ${call.function.name}`);
      continue;
    }
    
    try {
      const output = await handler(call.function.arguments);
      outputs.push(output);
    } catch (error) {
      outputs.push(`Error: ${error}`);
    }
  }
  
  return outputs;
}
```

--------------------------------

### Launch VS Code Extension

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/index.md

Start Nanocoder with the VS Code extension enabled for features like live diff previews and context-aware code analysis.

```bash
nanocoder --vscode
```

--------------------------------

### Structured Logging with Metadata

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/configuration/logging.md

Example of structured logging with Pino, including additional metadata such as userId, sessionId, and timestamp.

```typescript
logger.info('User login successful', {
    userId: 'user-123',
    sessionId: 'session-456',
    authenticationMethod: 'oauth2',
    timestamp: new Date().toISOString()
});
```

--------------------------------

### Legacy Schedule Migration Example (JSON)

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/skills.md

This JSON format represents a legacy schedule entry that needs to be migrated. It specifies a cron job and the command to execute.

```json
[
{"cron": "0 9 * * MON", "command": "/weekly-report"}
]
```

--------------------------------

### Create a New Agent

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/subagents.md

Use the /agents create <new_agent_name> command to create a new agent template and get AI assistance in writing its definition.

```bash
/agents create my-agent
```

--------------------------------

### Initialize AISDKClient with Factory Method

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/ai-sdk-client.md

Use the static `create()` factory method for asynchronous initialization of the AISDKClient. This method handles provider setup and ensures the client is ready for use.

```typescript
import {AISDKClient} from '@nanocollective/nanocoder';
import type {AIProviderConfig} from '@nanocollective/nanocoder';

const config: AIProviderConfig = {
  name: 'OpenRouter',
  type: 'openrouter',
  models: ['google/gemini-3.1-flash'],
  config: {
    baseURL: 'https://openrouter.ai/api/v1',
    apiKey: process.env.OPENROUTER_KEY,
  },
  requestTimeout: 30000,
};

// Use factory method for async setup
const client = await AISDKClient.create(config);
```

--------------------------------

### Start Nanocoder CLI with Custom VS Code Port

Source: https://github.com/nano-collective/nanocoder/blob/main/plugins/vscode/README.md

Run the Nanocoder CLI with VS Code support, specifying a custom port for the WebSocket server.

```bash
nanocoder --vscode --vscode-port 51821
```

--------------------------------

### Update Nanocoder installed via Homebrew

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/getting-started/installation.md

To update Nanocoder installed via Homebrew, first update Homebrew's tap cache and then upgrade the package. Ensure you run `brew update` before `brew upgrade` to get the latest formula.

```bash
# Update Homebrew's tap cache first (important!)
brew update

# Then upgrade nanocoder
brew upgrade nanocoder
```

--------------------------------

### GitHub Models Configuration

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/configuration/providers/github-models.md

Example JSON configuration for setting up GitHub Models as a Nanocoder AI provider. Ensure you replace placeholders with your actual PAT and model name.

```json
{
	"name": "GitHub Models",
	"baseUrl": "https://models.github.ai/inference",
	"apiKey": "your-github-pat",
	"models": ["your-model-name"]
}
```

--------------------------------

### Nix Flakes Configuration for Nanocoder

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/getting-started/installation.md

Example Nix configuration to integrate Nanocoder into your system packages. This involves defining the input and referencing it in your system's configuration.

```nix
# flake.nix
{
  inputs = {
    nanocoder = {
      url = "github:Nano-Collective/nanocoder";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}

# configuration.nix
{
  pkgs, inputs, system, ... }:
{
  environment.systemPackages = [
    inputs.nanocoder.packages."${system}".default
  ];
}
```

--------------------------------

### New Skill Subscription in Command Frontmatter

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/scheduler.md

Example of how to define a cron schedule subscription within a command's frontmatter in a Markdown file.

```markdown
<!-- .nanocoder/commands/weekly-report.md -->
---
description: Monday morning summary.
subscribe:
  - kind: schedule.cron
    cron: "0 9 * * MON"
---

Summarize last week's commits...
```

--------------------------------

### Initialize Project Configuration

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/index.md

Run /init to analyze your project and generate an AGENTS.md file, providing the AI with codebase context and conventions. Use --force to regenerate.

```bash
/init --force
```

--------------------------------

### Start Nanocoder with VS Code Integration via IDE Command

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/vscode-extension.md

Within a Nanocoder session, use the /ide command to open an interactive selector and choose VS Code for integration.

```bash
/ide
```

--------------------------------

### Setup MCP Server for Tools

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/index.md

Initiate the interactive wizard to set up Model Context Protocol (MCP) servers, which add new tools for the AI to use. View connected servers and tools with /mcp.

```bash
/setup-mcp      # interactive setup wizard
/mcp            # see connected servers and tools
```

--------------------------------

### Template Syntax Example

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/custom-tools.md

Demonstrates how template variables are substituted and shell-quoted in custom tool bodies. This prevents shell injection by properly escaping parameter values.

```markdown
echo {{ name }}
```

--------------------------------

### Tune Status Bar Summary

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/tune.md

When tune is active, the status bar displays a summary of the current settings. This example shows the 'minimal' profile with compaction enabled and a temperature of 0.7.

```text
tune: minimal | compact | temp:0.7
```

--------------------------------

### Start Nanocoder in Interactive Mode

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/cli-interface.md

Initiates Nanocoder in its default interactive mode, which includes a welcome message, provider selection, and a chat loop for user input.

```bash
nanocoder
```

--------------------------------

### Non-Interactive Mode Example

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/app-component.md

An example of configuring the App component for non-interactive mode to execute a single prompt and exit.

```typescript
// Example: Execute a prompt and exit
<App
  nonInteractiveMode={true}
  nonInteractivePrompt="Find all TypeScript errors"
  cliProvider="openrouter"
  cliMode="auto-accept"
/>
```

--------------------------------

### Subscription with Confirmation Prompt

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/skills.md

This example shows how to configure a subscription with `confirm: true`. This setting causes the triggered run to execute in 'plan' mode, allowing for review before applying changes, instead of the default 'headless' mode.

```yaml
subscribe:
  - kind: file.changed
    target: agent:docs-agent
    paths: ["docs/**"]
    confirm: true
```

--------------------------------

### Build Project

Source: https://github.com/nano-collective/nanocoder/blob/main/CONTRIBUTING.md

Build the project before running benchmark tests, as the benchmark reads from the dist/ directory. This step is crucial for accurate benchmark results.

```bash
pnpm run build         # the benchmark reads dist/, so build first
```

--------------------------------

### Install terminal-notifier for macOS

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/notifications.md

Install terminal-notifier using Homebrew to enable full notification support on macOS, including icons and click-to-focus behavior.

```bash
brew install terminal-notifier
```

--------------------------------

### AnthropicTokenizer Example

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/tokenization-api.md

Example of using `AnthropicTokenizer` for exact token counting with Claude models. Falls back to character estimation if the tokenizer is unavailable.

```typescript
const tokenizer = createTokenizer('anthropic', 'claude-opus-4');
const count = tokenizer.countTokens('The quick brown fox');
```

--------------------------------

### OpenAITokenizer Example

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/tokenization-api.md

Example of using `OpenAITokenizer` for exact token counting with OpenAI models. Falls back to character estimation if tiktoken fails.

```typescript
const tokenizer = createTokenizer('openai', 'gpt-4-turbo');
const count = tokenizer.countTokens('The quick brown fox');
```

--------------------------------

### Tap Nanocoder Repository for Homebrew

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/getting-started/installation.md

Before installing Nanocoder with Homebrew, you need to tap the official repository. This command adds the Nanocoder formula to your Homebrew installation.

```bash
brew tap nano-collective/nanocoder https://github.com/Nano-Collective/nanocoder
```

--------------------------------

### Custom Subagent Definition Example

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/subagents.md

Manual creation of a custom subagent in a markdown file. This example defines a 'code-reviewer' agent with specific tools and a system prompt.

```markdown
---
name: code-reviewer
description: Reviews code for bugs, security issues, and style problems
model: inherit
contextWindow: 16384
tools:
  - read_file
  - search_file_contents
  - find_files
  - list_directory
---

You are a code review specialist. When given a file or directory to review:

1. Read the code carefully
2. Search for related files to understand context
3. Identify bugs, security issues, and style problems
4. Return findings with file paths and line numbers
```

--------------------------------

### Install Nanocoder VS Code Extension Manually via CLI

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/vscode-extension.md

Use the VS Code CLI to install the Nanocoder extension by providing the path to the VSIX file.

```bash
code --install-extension /path/to/nanocoder-vscode.vsix
```

--------------------------------

### Basic Logging with Pino

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/configuration/logging.md

Demonstrates basic logging using the getLogger utility. Shows how to log messages at different levels from fatal to trace.

```typescript
import {getLogger} from '@/utils/logging';

const logger = getLogger();

logger.fatal('Critical system failure');
logger.error('Operation failed', {error: new Error('Test error')});
logger.warn('Resource limit approaching');
logger.info('Application started successfully');
logger.debug('Debug information', {details: 'verbose'});
logger.trace('Detailed trace information');
```

--------------------------------

### Non-Interactive CLI Exit Codes Example

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/app-component.md

Shows an example of how to execute a Nanocoder command in non-interactive mode and check the exit code. This illustrates success, error, timeout, and tool approval scenarios.

```bash
nanocoder --plain run "find errors" && echo "OK" || echo "Failed: $?"
```
```

--------------------------------

### Run Development Server

Source: https://github.com/nano-collective/nanocoder/blob/main/AGENTS.md

Watch mode compilation using tsc --watch.

```bash
npm run dev
```

--------------------------------

### Build and Run Commands (CLAUDE.md)

Source: https://github.com/nano-collective/nanocoder/blob/main/AGENTS.md

Commands for building, testing, and running the application, including watch mode compilation and credit regeneration.

```bash
pnpm run build          # Compile TypeScript to dist/ with executable permissions
pnpm run build:credits  # Regenerate contributors.json from git history (CI/release only)
pnpm run start          # Run the compiled application
pnpm run dev            # Watch mode compilation (tsc --watch)
```

--------------------------------

### Run with Provider and Model Specified

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/getting-started/index.md

Execute a prompt using a specific AI provider and model. This is useful for controlling costs and ensuring consistent model behavior.

```bash
nanocoder run --provider openrouter --model anthropic/claude-sonnet-4-20250514 "refactor database module"
```

--------------------------------

### getColors()

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/configuration.md

Get theme colors for the current UI theme.

```APIDOC
## getColors()

### Description
Get theme colors for the current UI theme.

### Returns
`Colors` — Theme color scheme

### Example
```typescript
import {getColors} from '@nanocollective/nanocoder';

const colors = getColors();
console.log(`Primary color: ${colors.primary}`);
```
```

--------------------------------

### Create a Kubernetes Pods Tool

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/custom-tools.md

Scaffold a new tool for listing Kubernetes pods. This markdown file defines the tool's name, description, parameters (namespace and optional selector), approval policy, and the shell command to execute.

```markdown
---
name: k8s_pods
description: List pods in a Kubernetes namespace. Returns kubectl output as text.
parameters:
  namespace:
    type: string
    required: true
    description: The Kubernetes namespace
    pattern: '^[a-z0-9-]+$'
    maxLength: 63
  selector:
    type: string
    description: Optional label selector (e.g. "app=api")
approval: never
read_only: true
---

kubectl get pods -n {{ namespace }} {{# selector }}-l "{{ selector }}"{{/ selector }}
```

--------------------------------

### Uninstall Nanocoder with Homebrew

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/getting-started/uninstalling.md

Use this command to uninstall Nanocoder if it was installed using Homebrew.

```bash
brew uninstall nanocoder
```

--------------------------------

### Boot Nanocoder into Development Mode

Source: https://github.com/nano-collective/nanocoder/blob/main/README.md

Launch Nanocoder directly into a specific development mode like 'yolo' or 'plan'. These modes alter the agent's behavior.

```bash
# Boot directly into a development mode (normal, auto-accept, yolo, plan)
nanocoder --mode yolo
nanocoder --mode plan run "audit the auth module"
```

--------------------------------

### Uninstall Nanocoder with NPM

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/getting-started/uninstalling.md

Use this command to uninstall Nanocoder if it was installed globally via npm.

```bash
npm uninstall -g @nanocollective/nanocoder
```

--------------------------------

### getAppConfig()

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/configuration.md

Get the cached app configuration. Loads on first call and caches until reloadAppConfig() is called.

```APIDOC
## getAppConfig()

### Description
Get the cached app configuration. Loads on first call and caches until `reloadAppConfig()` is called.

### Returns
`AppConfig` — Complete application configuration

### Example
```typescript
import {getAppConfig} from '@nanocollective/nanocoder';

const config = getAppConfig();
console.log(`Providers: ${config.providers?.map(p => p.name).join(', ')}`);
console.log(`Auto-compact enabled: ${config.autoCompact?.enabled}`);
```
```

--------------------------------

### Display Nanocoder Help Information

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/cli-interface.md

Use these flags to show the usage information, available commands, and options for the Nanocoder CLI. This is a fast path command.

```bash
nanocoder --help
```

```bash
nanocoder -h
```

--------------------------------

### Malformed Arguments Detection

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/tool-calling-api.md

Example of malformed arguments (string instead of object) and the resulting error from parseToolCalls.

```typescript
// Attempted but invalid:
{"name": "tool", "arguments": "not an object"}

// parseToolCalls() detects and returns:
{
  success: false,
  error: 'Invalid tool call: "arguments" must be an object, not a string'
}
```

--------------------------------

### CLI Entry Point Rendering App Component

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/app-component.md

Demonstrates how to render the App component from the CLI entry point, configuring it for non-interactive mode with specific provider and model settings.

```typescript
// From source/cli.tsx
import {App} from '@nanocollective/nanocoder';
import React from 'react';
import {render} from 'ink';

const {default: App} = await import('@/app/index.ts');

render(
  <App
    nonInteractiveMode={true}
    nonInteractivePrompt="Analyze src/app.ts"
    cliProvider="openrouter"
    cliModel="google/gemini-3.1-flash"
  />,
);
```

--------------------------------

### List All Available Subagents

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/subagents.md

Use the /agents command to display all available subagents, including their source, model, and tool count.

```bash
/agents
```

--------------------------------

### Build and Package VS Code Extension

Source: https://github.com/nano-collective/nanocoder/blob/main/plugins/vscode/README.md

Build the extension for production and package it into a .vsix file for distribution.

```bash
pnpm run build
pnpm exec vsce package --allow-missing-repository --skip-license --no-dependencies
```

--------------------------------

### Llama 3.x Function-Tag Format

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/tool-calling-api.md

Example of the Function-Tag format used by Llama 3.1+ and Mistral models.

```xml
<function=read_file>{"path": "file.txt"}</function>
```

--------------------------------

### getContextSize()

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/ai-sdk-client.md

Gets the cached context window size in tokens. This value is fetched after initialization and when the model changes.

```APIDOC
## Method: getContextSize()

### Description
Get cached context window size in tokens. Value is fetched from models.dev after initialization and when model changes.

### Method
`getContextSize(): number`

### Parameters
None

### Returns
- **number** — Context size in tokens (0 if not yet available)
```

--------------------------------

### Example Provider Configuration with Context Window Overrides

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/configuration/providers/index.md

This JSON snippet shows how to configure a local Ollama provider with a default context window and a specific override for a custom model. This is useful for setting up different context window sizes for different models within the same provider.

```json
{
  "nanocoder": {
    "providers": [
      {
        "name": "Local Ollama",
        "baseUrl": "http://localhost:11434/v1",
        "models": ["custom-model"],
        "contextWindow": 32768,
        "contextWindows": {
          "custom-model": 131072
        }
      }
    ]
  }
}
```

--------------------------------

### Get Available Models

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/ai-sdk-client.md

Fetch a list of all model names available from the configured provider. This is an asynchronous operation.

```typescript
const models = await client.getAvailableModels();
models.forEach(m => console.log(`- ${m}`));
```

--------------------------------

### Find Nanocoder Binary Location

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/getting-started/uninstalling.md

Use the 'which' command to locate the Nanocoder binary if you are unsure about its installation path.

```bash
which nanocoder
```

--------------------------------

### Inspecting and Creating Skills

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/features/skills.md

Commands for interacting with Nanocoder skills. Use `/skills show` to view details of a skill and `/skills create` to scaffold new skill bundles.

```bash
/skills                 list every loaded skill
/skills show k8s        details for one skill (members, subscriptions, source)
/skills create k8s      scaffold a new bundle at .nanocoder/skills/k8s/
```

--------------------------------

### AISDKClient.create()

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/ai-sdk-client.md

Factory method for asynchronous initialization of AISDKClient. This should be used instead of the constructor.

```APIDOC
## Static Method: create()

### Description
Factory method for asynchronous initialization of AISDKClient. Must be called instead of the constructor.

### Method
`static async create(providerConfig: AIProviderConfig): Promise<AISDKClient>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **providerConfig** (`AIProviderConfig`) - Required - Provider configuration

### Returns
- **Promise<AISDKClient>** — Fully initialized client ready for chat

### Throws
- **Error** - SDK package unavailable for configured provider
- **Error** - Invalid provider configuration
```

--------------------------------

### Run Nanocoder in YOLO Mode

Source: https://github.com/nano-collective/nanocoder/blob/main/docs/getting-started/index.md

Start an interactive Nanocoder session in 'yolo' mode, which allows for immediate execution of actions.

```bash
nanocoder --mode yolo
```

--------------------------------

### Provider Configuration with Context Window Overrides

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/models-api.md

Illustrates how to configure provider-specific context limits, including model-specific overrides within a JSON configuration.

```json
{
  "nanocoder": {
    "providers": [
      {
        "name": "Custom API",
        "baseUrl": "https://custom-api.local",
        "models": ["custom-model"],
        "contextWindow": 4096,
        "contextWindows": {
          "custom-model": 8192,
          "custom-model-large": 32000
        }
      }
    ]
  }
}
```

--------------------------------

### Run Nanocoder in Interactive Mode

Source: https://github.com/nano-collective/nanocoder/blob/main/README.md

Start Nanocoder interactively, specifying the AI provider and model. The CLI will then prompt for further actions.

```bash
# Interactive mode starting with specific provider
nanocoder --provider ollama --model llama3.1
```

--------------------------------

### Building a Token Counter

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/models-api.md

An example function that counts tokens in a given text for a specified model, utilizing getModelContextLimit and createTokenizer.

```typescript
import {getModelContextLimit, createTokenizer} from '@nanocollective/nanocoder';

async function countTokens(model: string, text: string) {
  const contextLimit = await getModelContextLimit(model);
  const tokenizer = createTokenizer('openai', model); // or provider name
  const tokens = tokenizer.countTokens(text);
  
  console.log(`Text: ${tokens} tokens`);
  console.log(`Context limit: ${contextLimit} tokens`);
  console.log(`Remaining: ${contextLimit - tokens} tokens`);
}

countTokens('gpt-4-turbo', 'Hello, world!');
```

--------------------------------

### Get Request Timeout

Source: https://github.com/nano-collective/nanocoder/blob/main/_autodocs/ai-sdk-client.md

Retrieve the configured socket timeout in milliseconds for requests. Returns undefined if the default timeout is used.

```typescript
const timeout = client.getTimeout();
console.log(`Timeout: ${timeout ?? 'default'}ms`);
```