Skip to content

Whittl Settings Reference

Preferences is at Edit > Preferences (Ctrl+,). It has eight panels: AI Generation, File Context, Image Generation, Vision (Image Input), Safety, Chat Appearance, Web Research, and Ollama. Everything else you can configure lives somewhere else in the app; the last two sections of this page say where.

Every change is written to settings.json in your Whittl data folder the moment you make it. There is no OK or Apply button.

AI Generation

Agent Mode (experimental)

Default: off

Gives the AI a longer leash on models that can use it. The tool loop may run 50 rounds on a tier-S model or 20 on tier-A (10 with this off), and the bash, web_search, web_fetch and download_file tools, plus full scripts in code mode, become available. The tier comes from each model's capability record, whichever backend serves it. Uses more tokens per request; leave it off for quick single edits. See Agent Mode.

AI Auto-Fix Errors

Default: on

Two things at once, which is why the label says errors and not just crashes:

  • After a crash, the AI tries to fix it: up to three attempts right after a generation, one for a crash while you are using the app (so it does not interrupt you).
  • On Test Run, Whittl's pattern rules are applied to your files before the app launches.

Turn it off and you get neither. The AI also stops editing files in response to review prompts, so feedback comes back as read-only commentary.

AI Investigation Before Generation

Default: on

A cheap AI pre-pass reads the selected code and builds a change plan before the main generation. Multi-file changes only. Off makes routing keyword-only: faster, less accurate on complex changes.

AI Asset Generation

Default: off

Lets the planner generate, change or regenerate image assets (sprites, icons, backgrounds). With it off, every visual or style request is treated as a code change, which is what you want for a utility app that draws its own graphics. Turn it on for games and sprite projects.

Include Claude Code skill paths

Default: on

Whittl also reads skills from ~/.claude/skills/ and .claude/skills/, beside its own ~/.whittl/skills/. A skill is a folder holding a SKILL.md, the way Claude Code stores one (a plain .md file in the folder works too); only the SKILL.md is read, so a skill's scripts and linked files are not loaded, and Claude's tool names are translated to Whittl's. Whittl's own skills win on a name conflict, and the Skills dialog marks each Claude skill it found.

Turn it off to keep the prompt to Whittl's own skills.

File Context

Send Active File Only

Default: off

Only the file open in the editor goes to the AI, whatever the project's size. The cheapest context, and the escape hatch when smart routing keeps leaving out a file you need, at the cost of any reasoning across files.

Smart Routing for All Projects

Default: off

Smart routing normally starts at 8 Python files. This lowers the threshold to 2, so small projects are routed too. Saves tokens, adds a little latency, and is occasionally too aggressive where sending everything was fine. See Smart File Routing.

Image Generation

Backend

Default: OpenRouter

Used for icon generation and AI asset creation.

Choice Notes
OpenRouter (Gemini Nano Banana) google/gemini-2.5-flash-image on your OpenRouter key. Roughly $0.04 per 1024x1024 image.
Gemini direct Needs a paid Gemini billing account; the free tier does not cover image generation.

Vision (Image Input)

Model

Default: Auto

When the model you are using cannot read images, this model describes your attached pictures and the description is sent instead. Auto uses the first that works among the providers you have set up: DeepSeek's vision model when DeepSeek is your backend, then OpenRouter (Claude Haiku 4.5 on your key), Gemini, Claude, and a local Ollama vision model. The other choices name one model: DeepSeek's experimental vision model, or an OpenRouter model from a free Gemma option up to Claude Sonnet 5 and GPT-5.4, each with its input price on the list.

On the Ollama backend only a local vision model is ever asked, whatever is chosen here, so your pictures stay on your machine. See Screenshot to App.

Safety

Confirm Before AI Changes

Default: on

Asks before the AI changes existing code: a click per change, and a chance to say no to one you did not expect. Turn it off once you trust the loop.

Chat Appearance

Picture

Default: a person icon

The picture beside your own messages in the chat. Choose picture... picks one, and you drag it inside the round preview to choose which part shows. The picture is copied into Whittl's own folder, so it keeps working if you move or delete the original. Use the default icon puts the icon back. A file that is not a picture Whittl can read is refused when you choose it, with the reason.

Name in the chat

Default: empty, which shows You

What your own messages are headed with. Whittl's replies are unchanged and still name the model that wrote each one.

Web Research

Caps on the AI's web tools, each per session; both reset when a new generation starts. They exist so a model cannot spend an afternoon chasing a lead that was never there. The tools themselves need Agent Mode.

Searches and page reads

Default: 20 (choices: 10, 20, 40, 60, 100)

How many times the AI may search the web or read a page.

File downloads

Default: 40 (choices: 10, 20, 40, 80, 150)

How many files the AI may save from the web. Counted apart from research, because fetching an icon set or a font family can be 15 to 30 files without looking anything up.

Ollama

Context length

Default: 16384 since v2.6.0, 8192 before (choices: 4096, 8192, 16384, 32768, 65536). A value you chose yourself is kept.

How much conversation and project code Ollama keeps in memory. Whittl sends this on every request, so it overrides the context length set in Ollama's own app.

Higher values need more RAM or VRAM, because the KV cache grows with the context, and they need a model that supports the length. 64K is heavy: on an 8B model the cache alone wants roughly 16 GB of VRAM, and many local models lose accuracy past about 32K. The dialog says so next to the slider when you drag it that far.

When a request uses most of the window (85% or more of it before the model has written anything), Whittl says so once in the chat, with the numbers. The context gauge shows the same thing as you work.

Settings that are not in Preferences

These are real controls, just somewhere else.

Setting Where it lives
API keys The key button beside the backend dropdown in the chat panel, or the first-run setup wizard
Backend and model The dropdowns at the top of the chat panel
Theme View > Switch to Dark / Light Theme
Chat font size The A- / A+ buttons at the top of the chat panel
Editor font size The A- / A+ buttons in the editor toolbar
Skill library (add, edit, disable, auto-learn) Edit > Custom Skills...
Plugins (the master switch, each plugin, holding back plugins that fail their examples) Edit > Plugins > Manage Plugins...
Whittl data folder Edit > Change Data Location...
Thinking The Think checkbox, and the depth dropdown where the backend offers levels
Explain mode The Explain button in the editor toolbar
The welcome tour, again Help > Show Welcome Tour
Updates Help > Check for Updates...
Orphaned project folders Help > Cleanup Orphaned Folders...

About updates

There is no startup check. The check runs only when you ask for it, downloads in the app, verifies the SHA-256, and offers "Restart to install". Since v2.5.0 it checks the download server against Whittl's own certificate bundle instead of the operating system's, which fixed a silent failure on some Windows machines. See Upgrading Whittl.

Skip this version is a button in the update dialog, not a setting. Once clicked, Whittl stops offering that version.

Keys with no dialog

Read from settings.json in your Whittl data folder. Edit the file with Whittl closed, or the app will write its own copy back over your change.

Key Default What it controls
web_search_enabled true Offer the web tools at all (they also need Agent Mode). See Web Research.
web_search_backend "duckduckgo" Search backend. DuckDuckGo needs no key.
web_fetch_max_chars 20000 Where a fetched page is cut off.
code_mode_enabled true Offer run_script, and let a model without reliable tool calling work through code mode.
app_probe_screenshot true probe_app takes a picture of the window, and Whittl shows it in the chat.
test_driven_iteration_enabled true Run the test gate after a generation.
test_driven_max_iterations 3 Iteration cap for the planned automatic fix loop; shown in the report today.
test_driven_test_timeout 60 Seconds one test run may take before the gate gives up on it.
skills_enabled true Put skills into prompts at all.
skills_token_limit 6000 Token budget for the skill block.
disabled_skills [] Skill files left out of prompts. The Custom Skills dialog writes this.
auto_learn_enabled true Record new patterns from successful fixes.
auto_learned_promotion_threshold 5 Hits before a pattern can be promoted into a curated skill.
auto_learned_auto_promote true Promote eligible patterns automatically at startup.
auto_learned_promote_min_models 1 How many different models must have hit a pattern before it can be promoted.
auto_learned_max_entries 50 Size cap on the staging file.
claude_skill_translation_enabled true Rewrite Claude Code tool names in its skills to Whittl's own.
ollama_tool_timeout 1200 Seconds to wait for a local model's tool round.
ui_theme "dark" Theme. The View menu writes this.
code_font_size 12 Editor font size. The A- / A+ buttons write this.
chat_font_size 13 Chat font size. The A- / A+ buttons write this.

What's next