Skip to content

Whittl FAQ

Questions that come up repeatedly on first-run, in email, and in reviews. If your question isn't here, the troubleshooting pages and contact page cover more ground.

General

Is Whittl free?

No. Whittl is a $20 CAD one-time purchase via LemonSqueezy. No subscription, no user limits, no month-over-month fees. You own the license forever. See the product page for the current price.

Is the AI free?

Whittl's app is paid, but the AI backends it talks to are mostly priced per use:

  • Gemini has a generous free tier — the default "just trying Whittl out" pick
  • OpenRouter has free models with rate limits (Qwen3-Coder, DeepSeek R1 free, Llama 3.3 free)
  • Ollama runs fully locally and costs nothing after initial setup
  • Claude, DeepSeek, paid OpenRouter models are pay-as-you-go at provider prices

See Choosing a Backend for cost breakdowns.

Does Whittl work offline?

Yes, with Ollama. Every other backend needs an internet connection. See Ollama.

What platforms are supported?

Windows 10/11 and Linux (Ubuntu 22.04+, Fedora 38+, Arch, Debian 12+, etc.). macOS is not supported and is not on the roadmap.

Android APK builds are experimental (Flet target only). See Mobile Builds.

Do I need Python installed?

No. Whittl bundles its own Python runtime. The Windows installer drops Python 3.11+ into %LOCALAPPDATA%\Whittl\bundled_python\. Linux AppImage ships Python inside the AppImage.

Can I use my own Python interpreter?

Not for Whittl itself (it uses the bundled runtime for its own code), but projects you generate can run on any Python 3.10+ you install separately. When you build an installer via the Build dialog, Python gets bundled into the output — your users don't need Python installed either.

Generation & AI

What happens if I hit the Gemini free tier limit?

You get a rate-limit error from Gemini's API. Whittl surfaces it in the chat. Options:

  1. Wait — the free tier resets after a cooldown
  2. Switch to another backend via the dropdown (your prompt stays; no need to retype)
  3. Add billing to your Google AI account to upgrade to paid tier

Can I use multiple backends in the same project?

Yes. Switch via the dropdown in the chat panel. Conversation history carries forward. Common pattern: Gemini Flash for rapid iteration, Claude Sonnet for a tricky fix, back to Flash.

Why does my generation say "3 of 27 files sent"?

That's Smart File Routing. Whittl only sends files relevant to your current request, not the whole project. Reduces cost and keeps the AI focused.

Can I stop a generation mid-stream?

Yes. Click the Stop button in the chat panel. Active generation cancels, any code written so far stays. The auto-fix cycle also respects Stop — it finishes the current round and exits cleanly.

Does the AI remember past conversations?

Within a session, yes. Across sessions, chat history is saved per project and replayed on reopen.

Can the AI edit my files without my approval?

Yes — that's the primary mode. Whittl's autofix rules catch hallucinated APIs and common mistakes before applying. Test Run (F5) is the quickest way to verify a change didn't break anything. Ctrl+Z rolls back the most recent edit. The Archives tab snapshots every generation for full rollback. See Recovering from a Bad Generation.

Does Whittl have a built-in terminal?

Yes. The Terminal tab in the preview panel shows live output from Test Run and lets you run arbitrary commands (pip list, python --version, custom scripts) in your project folder. If the project has a venv/ subfolder, python and pip auto-route through it. Each command has a 60-second timeout, and shell features like pipes, redirects, and && chains don't work (use your OS shell for those). Full write-up in Debugging → The terminal panel.

Can the AI explain or fix just a snippet without touching the rest of the file?

Yes. Select the code, right-click, and pick Explain Selection or Fix Selection with AI. The AI operates only on the selection; the rest of the file is untouched. There's also a whole-file Explain Mode toggle in the editor toolbar that adds inline #: comments throughout. See Explain Mode & Inline AI Help.

Privacy & Security

Does Whittl send my code anywhere?

Only to the AI backend you selected. See Privacy & Data Flow for the full breakdown.

How are my API keys stored?

Encrypted in ~/.whittl/settings.json using a machine-derived Fernet key. Copying the file elsewhere gives attackers junk. See Privacy.

Does Whittl phone home?

No telemetry. The only outbound requests Whittl initiates on its own are update checks (when you click) and a one-time license validation. See Privacy.

Files & Projects

Where are my projects?

~/.whittl/projects/ on Linux, %USERPROFILE%\.whittl\projects\ on Windows. Each project is a regular folder of .py files you can open in any editor. See Folder Structure.

Can I version my projects with git?

Yes. cd into the project folder, git init, commit away. Whittl's internal files (project.json, _whittl_launcher.py, archives/) can be committed or gitignored as you prefer.

Can I edit files outside Whittl?

Yes. Whittl reloads files on focus-in. Use VS Code, Emacs, whatever. Be mindful that while a generation is in progress, Whittl is writing to files — don't edit at the same time or you'll collide.

How do I export a project?

Right-click the project in the sidebar → Save as Template. Produces a .whittl-template file packaging the project (minus archives). To get a raw zip, copy the project folder out of ~/.whittl/projects/ — it's real files. See Templates.

How do I back up everything?

Copy ~/.whittl/ (Linux) or %USERPROFILE%\.whittl\ (Windows) to backup storage. That's projects + settings + skills + templates + favorites. See Folder Structure.

Build & Distribution

Can I sell the apps I make with Whittl?

Yes. The .py files are yours. PySide6 is LGPL (free for commercial use with dynamic linking). You own your code and your builds.

Why is my built .exe so large?

PyInstaller bundles Python + Qt + your dependencies. A typical PySide6 app is 80-120 MB. CustomTkinter apps ship 15-25 MB. General Python CLI tools ship 10-30 MB. See Building an Installer.

Can I attach a EULA or user guide to the installer?

Yes. In the Build dialog, tick Create Windows installer to reveal the installer options. The EULA File picker takes a .txt or .rtf file and makes users accept it before install. The Include with installer list lets you attach any files (user guides, READMEs, sample data, etc.) that land in the install folder alongside the executable. See Building an Installer.

Are Whittl's builds code-signed?

No, not as of v2.4. Windows SmartScreen shows "Unknown publisher" on first install. Clicking "More info" → "Run anyway" gets past it. Signing certs cost ~$120/year — deferred until Whittl revenue supports it.

Upgrading

How do I update Whittl?

From v2.4 onward: Help → Check for Updates inside the app. Download runs in-app, click "Restart to install" when done. See Upgrading Whittl.

Before v2.4 (v2.3 and earlier): Check for Updates opened the browser, you downloaded the installer, ran it manually.

Will my projects survive an upgrade?

Yes. Every Whittl version reads ~/.whittl/ without migration. Your projects, settings, skills, templates are all format-stable.

What's next