Skip to content

Whittl Settings Reference

Whittl's Preferences dialog is at Edit → Preferences (Ctrl+,). This page is the reference for every setting, grouped by panel.

AI Generation

Controls how the AI generates and modifies code.

Agent Mode

Default: off

Opt-in unbounded tool-use loop for capable models. See Agent Mode for the full explanation. When on, tier-S/A models run up to 20-50 rounds per prompt instead of the default 5-7. Expensive on premium models; enabling unintentionally can burn credit fast.

Enable AI Auto-Fix

Default: on

When a generated app crashes, Whittl's AI auto-fix iterates on surgical edits up to the hard round cap. Turn off to see raw AI output without auto-fix intervention — useful when debugging generation issues.

Note: the static (regex-based) auto-fix rules always run. This toggle only controls the AI-powered iterating auto-fix after a crash.

Confirm Before AI Changes

Default: off

When on, Whittl shows a confirmation dialog before applying AI-generated code modifications. Adds friction but gives you a chance to reject unexpected changes.

Useful while learning Whittl. Most experienced users turn it off.

Asset Generation

Default: off

Enables AI-generated sprites, icons, and textures for game projects. When on, Whittl's asset pipeline analyzes your code for sprite needs and offers to generate missing art. When off, sprite-related prompts are clamped to code-only changes.

Turn on only if you're making games that need AI-generated art. Turning on for utility apps wastes tokens.

Smart File Routing

Default: on for projects with 8+ files, off otherwise

When on, large projects only send relevant files to the AI, saving 4-15× tokens per modification. The status bar shows "Smart routing: X of Y files" when active.

Sub-toggle: Smart Routing for All Projects — lowers the threshold so smart routing fires even on 2+ file projects. Useful for very cost-sensitive workflows; occasionally too aggressive for small projects where sending everything is fine.

Send Active File Only

Default: off

Escape hatch for when smart routing excludes a file you need. When on, only the currently-focused editor tab goes to the AI regardless of project size. Disables cross-file reasoning but guarantees you know exactly what's in the prompt.

Enable Prompt Expansion

Default: on

The Expand checkbox in the chat panel uses this. When enabled, short / vague prompts ("calculator") get expanded into detailed specs before going to the AI. When disabled, the Expand checkbox does nothing.

Investigation Enabled

Default: on for large projects

When on, Whittl runs a quick AI-assisted "which files are relevant" pass before the main generation. Part of smart routing. Disabling makes routing keyword-only (faster but less accurate).

Chain of thought / Thinking mode

Default: off

For models that support extended thinking (DeepSeek R1, Claude extended-thinking, OpenAI o1-style reasoning), enables the explicit reasoning chain. Costs more tokens but can improve quality on complex tasks.

The Think checkbox in the chat panel overrides this per-request.

Appearance

Theme

Default: dark

Whittl's dark or light theme. See Themes.

Can also be toggled via the View menu (View → Switch to Dark / Light Theme).

Chat font size

Default: 13pt

Size of chat panel text. Persists per install. Keyboard-adjustable with A- / A+ buttons in the chat panel header.

Code editor font size

Default: 12pt

Size of code editor text. Persists per install. Keyboard-adjustable with A- / A+ buttons in the editor header.

Code editor font

Default: system default monospace

Can override to a specific font. Popular picks: JetBrains Mono, Fira Code, Cascadia Code, Consolas.

Backends

Claude API Key, Gemini API Key, DeepSeek API Key, OpenRouter API Key

Per-backend API key fields. Encrypted at rest on disk with a machine-derived key (Fernet). See Setting Up API Keys for where to get each one.

Preferred backend

Default: whatever you picked in the setup wizard

Which backend Whittl selects on app launch. Can be changed mid-session via the dropdown in the chat panel; this setting is just the startup default.

Ollama Host

Default: http://localhost:11434

Ollama daemon URL. Change if your Ollama is running on a different port or on a remote machine.

Editor

Autocomplete

Default: on

Whether autocomplete suggestions pop up while you type. Uses jedi for Python completions. Turn off if it feels intrusive on slow machines.

Real-time error detection

Default: on

Shows red squiggles under errors in real time via pyflakes. Turn off on very large files if performance suffers.

Bracket auto-pair

Default: on

When you type (, Whittl auto-inserts ) and positions the cursor between them. Standard IDE behavior.

Indent size

Default: 4 spaces

Python convention. Can change to 2 spaces or tabs if your project requires a different style.

Projects

Default project target

Default: Desktop (PySide6)

Which framework target is preselected when you create a new project. Options: Desktop (PySide6), Mobile (Flet), Basic (CustomTkinter), General Python.

Default project venv

Default: off

Whether new projects get isolated per-project virtual environments. Off is faster (shared bundled Python, no venv creation overhead). On is safer (projects with conflicting dependencies don't step on each other).

Updates

Check for updates on startup

Default: on (but non-intrusive; see below)

Whether Whittl checks R2 on startup for a newer version. Currently the startup check emits a status-bar message only (no dialog). The v2.4 in-app updater will make this more visible. To disable entirely: uncheck.

Skip this version

Not a checkbox — a button that appears in the Update dialog. Once clicked, Whittl won't nag about the specific version it was shown for.

Channel (v2.4+)

Default: Stable

When the in-app updater ships in v2.4, this dropdown will let you choose Stable / Beta / Canary update channels. Not yet exposed in v2.3.

Advanced

Whittl data directory

Default: ~/.whittl/

Where Whittl stores projects, settings, skills, and the bundled Python. Changing this moves existing data to the new location. Useful if you have a small system drive and want projects on a secondary drive.

Verbose logging

Default: off

When on, Whittl prints detailed internal logs to the terminal panel. Useful for reporting bugs or diagnosing issues.

Skill library enabled

Default: on

Whether Whittl's skill files (~/.whittl/skills/*.md) are injected into system prompts. Turning off disables the entire skills system for the session — not recommended, but useful if you're debugging a specific interaction between skills and output quality.

What's next