Skip to content

tune.md

Latest commit

 

History

History
176 lines (117 loc) · 9.8 KB

tune.md

File metadata and controls

176 lines (117 loc) · 9.8 KB
Raw
title Tune
description Runtime model tuning for tool profiles, compaction, native tool calling, and model parameters
sidebar_order 11

Tune

The /tune command opens a modal UI for adjusting runtime model behaviour. It lets you change tool profiles, compaction strategy, native tool calling, and model parameters without restarting Nanocoder.

Applying a change in /tune clears the current chat history, because the tool profile changes which tools and prompt the model sees. Save anything you need first.

Settings are persisted to nanocoder-preferences.json and restored on next launch.

Opening Tune

Type /tune in the chat input. Use arrow keys to navigate, Enter to select, and Esc to cancel.

Settings

Enabled / Disabled

The top menu item toggles tune on or off. Tune is on by default, with the auto tool profile. When disabled, the full tool set, native tool calling and default model parameters are used. When enabled, the full settings menu appears.

Tool Profile

Controls which tools the AI has access to.

Profile Tools Behaviour
auto (default) Resolves to full, minimal, or nano from the active model id Cloud/unknown models get full; models up to 15B parameters get a reduced profile automatically
full All registered tools including MCP servers No filtering applied
minimal 8 core tools: read_file, write_file, string_replace, execute_bash, find_files, search_file_contents, list_directory, agent Slim prompt and single-tool enforcement enabled automatically
nano 5 core tools: read_file, diff_edit, write_file, execute_bash, search_file_contents Ultra-slim prompt, single-tool enforcement, AGENTS.md omitted by default

The auto profile is the default. It keeps the full tool surface for cloud models and model ids with no size hint, resolves models up to 15B parameters to minimal, and resolves models up to 4B parameters to nano. The status bar shows the resolved profile, for example tune: minimal (auto).

What about tasks and walkthroughs? write_tasks and write_walkthrough are part of the full profile only. Under minimal or nano the AI will not build a task list or record a completion walkthrough — that prompt and tool budget is spent on editing instead. /tasks still works for managing the list yourself. Plan mode is the exception: write_plan is added back on every profile so plan review works everywhere. See Task Management and Development Modes.

Why don't I see my MCP tools? MCP tools are only exposed in the resolved full profile. If you connect an MCP server but the model cannot see its tools, open /tune and either switch the tool profile to full or use a larger/cloud model so auto resolves to full. /mcp still shows connected servers even when the current tool profile filters their tools out of the model prompt.

The minimal profile is designed for small models (1B-15B parameters) that struggle with large tool sets. It reduces the system prompt size and forces the model to call one tool at a time.

The nano profile is designed for the smallest models or low-end hardware running larger models locally. It is strictly more aggressive than minimal:

  • Drops find_files, list_directory, and agent (subagent delegation).
  • Drops the CORE PRINCIPLES and CODING PRACTICES prompt sections.
  • Uses shortened TASK APPROACH, FILE OPERATIONS, CONSTRAINTS sections (≤4 lines each).
  • Replaces the verbose SYSTEM INFORMATION block with a single-line ## SYSTEM line.
  • Omits AGENTS.md from the system prompt by default (override with the Include AGENTS.md toggle).

Together these reduce the system prompt from ~500–700 tokens (minimal) to roughly ~150–250 tokens (nano), leaving more of the context window for actual work.

Include AGENTS.md

Toggles whether AGENTS.md from the project root is appended to the system prompt.

  • Defaults ON for full and minimal profiles (preserves prior behaviour).
  • Defaults OFF for the nano profile, including when auto resolves to nano for the active model.
  • Can be flipped explicitly per session, persisted via preferences, or pinned in agents.config.json via tune.includeAgentsMd.

Disabling this is useful on tiny models that get crowded out by long project guidelines.

Aggressive Compact

When enabled, sets the auto-compact threshold to 50% (the lowest supported threshold) and mode to aggressive. This compresses conversation history earlier and harder, which helps models with small context windows.

It applies whenever the active tune has it on, including tune restored from preferences or config at startup. A threshold or mode you set yourself with /compact --threshold or the /compact flags for the session takes priority, and toggling tune does not clear it.

Native Tool Calling

Cycles through three tool-calling modes:

  • ON (toolMode: "native", the default) - tools go through the provider's native tool calling API.
  • OFF (XML fallback) (toolMode: "xml") - tools are described in the system prompt and the model emits XML tool calls.
  • OFF (JSON fallback) (toolMode: "json") - tools are described in the system prompt and the model emits JSON tool calls.

The fallbacks can help with models that have unreliable native tool support.

Model Parameters

Fine-tune the model's generation parameters:

Parameter Range Description
Temperature 0.1 - 2.0 Controls randomness. Lower = more focused, higher = more creative
Top P 0 - 1.0 Nucleus sampling. Lower = fewer token choices considered
Top K 1 - 200 Limits token choices to top K candidates
Max Tokens 64 - 32768 Maximum response length
Frequency Penalty -2.0 - 2.0 Penalises repeated tokens. Higher = less repetition
Presence Penalty -2.0 - 2.0 Penalises tokens already used. Higher = more topic diversity

Press Enter on a parameter to cycle through values. Select Reset All to Defaults to clear all parameter overrides.

Provider-specific parameters

Some providers accept additional reasoning controls that are configured through agents.config.json rather than the /tune modal:

  • reasoningEffort / reasoningSummary — reasoning controls for OpenAI Responses API models (GPT-5, o-series) via the chatgpt-codex provider. reasoningEffort is also forwarded to OpenRouter as reasoning.effort.

OpenRouter exposes additional always-on request body fields (provider routing, plugins, service tier, fallback models, etc) on the provider config itself — see OpenRouter request options. Those settings are not tied to tune and apply on every request.

Presets

Three built-in presets are available via Load Preset:

Preset Settings
Default Resets everything to defaults (tune enabled, auto profile, no aggressive compact)
Small Model Minimal tool profile, aggressive compact, temperature 0.7
Nano (low-end hardware) Nano profile, aggressive compact, AGENTS.md off, temperature 0.4, max tokens 2048

Selecting a preset populates the tune form — you can further adjust settings before applying.

Configuration Layers

Tune settings resolve from these layers, lowest priority first (later layers win):

  1. Hardcoded defaults - enabled: true, toolProfile: 'auto', aggressiveCompact: false
  2. Per-provider config - tune on a provider entry in nanocoder.providers
  3. Preferences - saved by the /tune UI to nanocoder-preferences.json
  4. Top-level config - nanocoder.tune in agents.config.json
  5. Session - changes made with /tune in the current session

Because top-level config sits above preferences, a nanocoder.tune block in agents.config.json wins over whatever /tune saved last time once you restart. Use /tune for per-session experiments, or remove nanocoder.tune if you want the saved preferences to stick.

Example: Per-Provider Config

Set defaults for a specific provider in agents.config.json:

{
  "nanocoder": {
    "providers": [
      {
        "name": "Ollama",
        "baseUrl": "http://localhost:11434/v1",
        "models": ["qwen2.5-coder:7b"],
        "tune": {
          "enabled": true,
          "toolProfile": "minimal",
          "aggressiveCompact": true
        }
      }
    ]
  }
}

This applies the minimal profile and aggressive compact while the Ollama provider is active, unless your preferences or a top-level nanocoder.tune block set those fields.

Interaction with Development Modes

Tune works alongside development modes:

  • Plan mode + minimal profile - the model gets read_file, find_files, search_file_contents, list_directory and agent for exploration, plus write_plan
  • Plan mode + nano profile - the model gets read_file and search_file_contents for exploration, plus write_plan, with the shortened plan-mode prompt
  • Plan mode + full profile - all plan-mode tools are available, including read-only git, diagnostics, web, and interaction tools
  • Mode exclusions are filtered on top of the tune profile

Status Bar

When tune is enabled, the status bar shows the resolved tool profile. When the profile is auto, wide terminals also mark it:

tune: minimal (auto)

On narrow terminals the (auto) marker is dropped.

Related