Skip to content

Whittl Settings Reference

Preferences is at Edit → Preferences (Ctrl+,). It holds six panels and nothing else: AI Generation, File Context, Image Generation, Vision (Image Input), Safety, and Ollama. Everything else you can configure lives somewhere else in the app, and the last two sections of this page say where.

Everything is written to settings.json in your Whittl data directory as soon as you change it. There is no OK/Apply button.

AI Generation

Agent Mode (experimental)

Default: off

Gives capable models a different runtime: the planner is skipped, the tool loop runs long instead of capped, session memory persists across prompts, and the bash, web_search and web_fetch tools become available. See Agent Mode.

Expensive on premium models. Turning it on by accident and leaving it on is the fastest way to burn credit.

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 gets rounds to fix the error, up to the hard cap of 5.
  • 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. The pattern rules still tidy freshly generated code on its way into the editor; what stops is Whittl touching files you already have.

AI Investigation Before Generation

Default: on

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

AI Asset Generation

Default: off

Lets the planner generate, modify 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 game and sprite projects. Leaving it on for utility apps wastes tokens on art nobody asked for.

Include Claude Code skill paths

Default: on

Whittl also reads skill files from ~/.claude/skills/ and .claude/skills/ in addition to its own ~/.whittl/skills/. Free interop with Claude Code and OpenCode libraries; Whittl's own skills win on filename conflicts.

Turn it off to bound token usage to Whittl's own skills. The injection log prints a per-source character breakdown, so you can see whether foreign skills are inflating the prompt before you decide.

File Context

Send Active File Only

Default: off

Only the currently open file goes to the AI, whatever the project size. Cheapest possible context and the escape hatch when smart routing keeps excluding a file you need, at the cost of all cross-file reasoning.

Smart Routing for All Projects

Default: off

Smart routing normally starts at 8 or more Python files. This lowers the threshold to 2, so small projects get routed too. Saves tokens, adds a little latency, occasionally too aggressive on a project 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) Routes to google/gemini-2.5-flash-image on your existing OpenRouter key. Roughly $0.04 per 1024x1024 image.
Gemini direct Requires a paid Gemini billing account. The free tier no longer covers image generation.

Vision (Image Input)

Model

Default: Auto

Used when you attach a screenshot or a reference image to the chat. Auto tries your code-generation backend first if it supports vision, then falls back through Gemini, Claude and Ollama. The other choices route image input through OpenRouter on your existing key, independently of which model writes the code.

If you pick an OpenRouter vision model without an OpenRouter key configured, the request falls back to the Auto chain. See Screenshot to App.

Safety

Confirm Before AI Changes

Default: on

Shows a confirmation dialog before the AI modifies existing code. Adds a click per modification and gives you a chance to reject a change you did not expect. Turn it off once you trust the loop.

Ollama

Context length

Default: 8192 (choices: 4096, 8192, 16384, 32768, 65536)

How much conversation and project code Ollama keeps in memory. Whittl sends this on every request, so it overrides the context length configured 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 actually 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.

Settings that are not in Preferences

These are real controls, just somewhere else.

Setting Where it lives
API keys The key button next to the backend dropdown in the chat panel, or the first-run setup wizard
Backend and model The dropdowns in the chat panel header
Theme View → Switch to Dark / Light Theme
Chat font size The A- / A+ buttons in the chat panel header
Editor font size The A- / A+ buttons in the editor toolbar
Skill library (add, edit, disable, auto-learn) Edit → Custom Skills...
Whittl data directory Edit → Change Data Location...
Prompt expansion The Expand checkbox in the chat panel; the state persists
Thinking The Think checkbox, and the depth dropdown where the backend offers levels
Explain mode The Explain button in the editor toolbar
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-app, verifies the SHA-256, and offers "Restart to install". Since v2.5.0 it verifies the download server against Whittl's own certificate bundle instead of the operating system's, which is what fixed a silent failure on some Windows machines. See Upgrading Whittl.

Skip this version is a button in the update dialog, not a checkbox in a settings panel. Once clicked, Whittl stops offering the specific version it was shown for.

Keys with no dialog yet

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

Key Default What it controls
web_search_enabled true Offer the web tools at all. Still requires Agent Mode. See Web Research.
web_search_backend "duckduckgo" Search backend. DuckDuckGo needs no key.
web_search_max_per_session 20 Combined budget for searches and page reads per session.
web_fetch_max_chars 20000 Truncation point for a fetched page.
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 a single test run may take before the gate gives up on it.
skills_enabled true Inject skills into prompts at all.
skills_token_limit 5500 Token budget for the assembled skill block.
disabled_skills [] Skill filenames excluded from injection. 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 is eligible for promotion into a curated skill.
auto_learned_auto_promote true Promote eligible patterns automatically at startup.
auto_learned_promote_min_models 1 How many distinct models must have hit a pattern before it can be promoted.
auto_learned_max_entries 50 Hard size cap on the staging file.
claude_skill_translation_enabled true Rewrite Claude Code tool names in ingested 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