Project Folder Structure¶

Every Whittl project lives in its own folder under ~/.whittl/projects/ (Linux) or %USERPROFILE%\.whittl\projects\ (Windows). This page explains what's inside.

Typical project layout¶

~/.whittl/projects/todo_27176a00/
├── main.py                    <- entry point (always named main.py)
├── README.txt                 <- human-readable project description
├── project.json               <- Whittl metadata
├── _whittl_launcher.py        <- internal launcher wrapper
│
├── assets/                    <- user-provided images, sounds, fonts
│   └── logo.png
│
├── data/                      <- runtime data (protected from AI overwrites)
│   └── settings.json
│
├── archives/                  <- version history snapshots
│   ├── v1_20260401_143022/
│   ├── v2_20260401_144500/
│   └── ...
│
├── ui/                        <- optional UI subfolder (AI-generated)
│   ├── __init__.py
│   ├── main_window.py
│   └── dialogs.py
│
├── core/                      <- optional data/model subfolder
│   ├── __init__.py
│   └── database.py
│
└── ... (other generated files and folders)

The folder name suffix (_27176a00) is a short random hash so two projects with the same human-readable name can coexist.

File-by-file breakdown¶

`main.py`¶

The entry point. Whittl always names the entry file main.py. When you hit Test Run, this is what gets executed.

Safe to edit: yes, either in Whittl's editor or externally. Safe to delete: no. Whittl expects this file to exist.

`README.txt`¶

A human-readable summary of what the project does. Usually autogenerated by Whittl from the project name and the first user prompt. You can edit it to your liking.

Safe to edit: yes. Safe to delete: yes (Whittl regenerates a blank one next time you save).

`project.json`¶

Whittl's metadata for the project — name, target framework, venv flag, icon override, creation timestamp, and a few other fields. Example:

{
  "id": "27176a00",
  "name": "todo",
  "target_framework": "pyside6",
  "created_at": "2026-04-17T14:32:15Z",
  "use_venv": false,
  "metadata": {
    "icon": "list-checks"
  }
}

Safe to edit: yes, carefully. Changing name renames the project in the sidebar. Setting metadata.icon overrides the auto-matched icon. Safe to delete: if you delete this, Whittl treats the folder as an orphan and offers to archive or re-adopt it.

`_whittl_launcher.py`¶

An internal launcher script that Whittl writes before running your app. Handles logging setup, offscreen mode for the quick test, error capture for auto-fix, and a few other internal concerns.

Safe to edit: no. Whittl overwrites it on every run. Safe to delete: it gets regenerated on every Test Run.

`assets/`¶

User-provided assets — images, sounds, fonts, whatever your app needs. Whittl preserves this folder across generations and the AI won't overwrite files here by default.

Drop an image into the Assets panel and it lands here. Your generated code references it as assets/filename.ext.

Safe to edit: yes — this is YOUR folder. Safe to delete: yes, but then your app won't find its assets at runtime.

`data/`¶

Runtime data — saved user state, databases, logs. Whittl protects this folder from AI overwrites so the user's data persists across generations.

When you ask the AI to "reset this app to defaults," it typically generates code that writes to data/ but Whittl prevents it from deleting existing data files unless you explicitly prompt for that.

Safe to edit: yes, but usually this folder is populated by the app itself at runtime. Safe to delete: yes, but you'll lose the app's persistent state.

`archives/`¶

Version history. Every time the AI modifies the project, Whittl snapshots the current state to archives/vN_<timestamp>/. You can roll back to any previous version from the History panel.

Typical archive folder layout:

archives/v3_20260405_093015/
├── main.py
├── assets/       (copy of assets at snapshot time)
├── ... (copy of all project files at that moment)
└── .metadata    (snapshot info: prompt, timestamp, diff summary)

Safe to edit: no. These are frozen history snapshots. Safe to delete: yes. Deleting an archive just removes that rollback point. Safe to prune old archives manually if the folder gets huge.

Subfolders (ui/, core/, views/, etc.)¶

Generated by the AI when you have a multi-file project. Standard Python package structure with __init__.py per folder. Whittl treats any subfolder in the project root as a local module (doesn't try to pip-install it).

Safe to edit: yes. Safe to delete: only if you also remove imports that reference them, otherwise the app won't run.

What's outside the project folder¶

Whittl's data directory (`~/.whittl/`)¶

~/.whittl/
├── projects/              <- all your projects
│   ├── todo_27176a00/
│   └── weather_a4fe3b8b/
│
├── settings.json          <- encrypted API keys + preferences
├── skills/                <- skill library (see Skills System)
├── templates/             <- saved project templates
├── apk_tools/             <- downloaded Flet/Android build toolchain (first APK build)
├── model_cache/           <- cached OpenRouter model catalog + capability metadata
├── logs/                  <- Whittl's internal log files
│   ├── whittl.log         <- main app log (rotating, last 5 kept)
│   └── generation.log     <- AI generation event log
├── bundled_python/        <- (Linux only) bundled Python runtime
├── crash.log              <- Whittl's own crash log (fatal errors only)
└── update_cache/          <- downloaded installers pending apply (v2.4+)

Backing up ~/.whittl/ preserves all your projects, settings, skills, and templates. Everything Whittl knows about you.

Where files live per-platform¶

Path type	Linux	Windows
User data root	`~/.whittl/`	`%USERPROFILE%\.whittl\`
Projects	`~/.whittl/projects/`	`%USERPROFILE%\.whittl\projects\`
Settings + keys	`~/.whittl/settings.json`	`%USERPROFILE%\.whittl\settings.json`
Skills	`~/.whittl/skills/`	`%USERPROFILE%\.whittl\skills\`
Logs	`~/.whittl/logs/`	`%USERPROFILE%\.whittl\logs\`
Installed app binary	`/opt/Whittl/` or `~/.local/share/Whittl/`	`%LOCALAPPDATA%\Programs\Whittl\`
Bundled Python	(inside AppImage)	`%LOCALAPPDATA%\Whittl\bundled_python\`
Update cache (v2.4+)	`~/.whittl/update_cache/`	`%LOCALAPPDATA%\Whittl\updates\`

The app binary location (%LOCALAPPDATA%\Programs\Whittl\ on Windows) is different from the user data location (%USERPROFILE%\.whittl\) on purpose — uninstalling Whittl removes the binary, but your user data stays intact for the next install. Projects survive uninstall / reinstall / version change.

API key storage¶

API keys live encrypted inside ~/.whittl/settings.json:

Encryption: Fernet (AES-128-CBC + HMAC-SHA256)
Key derivation: machine-specific — derived from the local machine ID, NOT from a user password
What this means: copying settings.json to another machine decrypts to junk. Your keys are safe against casual leakage (e.g., a shared cloud backup) but NOT against an attacker with local machine access.
What this does NOT mean: it's not full-disk encryption. An attacker with code execution on your machine can read the keys. For stronger isolation, use BitLocker / LUKS / FileVault.

See Privacy & Data Flow for the complete data-handling story.

Log files¶

Whittl writes logs to ~/.whittl/logs/:

whittl.log — the main application log. Startup events, backend switches, generation outcomes, settings changes. Rotated on every launch; last 5 kept.
generation.log — AI generation events: prompt summaries, backend, token counts, autofix rounds. Useful for reviewing session costs.
crash.log — written only when Whittl itself crashes (not when a user project crashes — those go to the Terminal tab).

Safe to delete. Whittl regenerates them as needed.

Caches¶

model_cache/ — OpenRouter's model catalog JSON, refreshed on demand. Safe to delete; next OpenRouter use re-fetches.
apk_tools/ — ~200 MB of Flet / Android build toolchain downloaded on first APK build. Safe to delete; next APK build re-downloads.

Bundled Python runtime¶

On Windows, Whittl's bundled Python lives at:

%LOCALAPPDATA%\Whittl\bundled_python\
└── python\
    ├── python.exe
    ├── Lib/            <- stdlib + installed pip packages
    └── ...

On Linux AppImage, the runtime is inside the AppImage itself (you don't need to manage it). On Ollama setups, Ollama's models are separate again at ~/.ollama/.

Do NOT edit files in bundled_python/ manually. It's pip's territory. If you need to install something globally for Whittl to use, do it via Whittl's terminal panel: pip install <package>.

Backing up your work¶

Copy ~/.whittl/ to backup storage. Brings all projects, settings, skills.

Minimal backup (just projects, not settings): copy ~/.whittl/projects/.

Right-click the project in the sidebar → Save as Template.
Whittl packages the project folder (minus archives) into a .whittl-template file.
Share the .whittl-template file.

See Sharing a Project as a Template.

Moving a project between machines¶

Copy ~/.whittl/projects/<project_name>_<id>/ to the other machine's ~/.whittl/projects/ directory. Relaunch Whittl on the target machine; the project appears in the sidebar.

What's next¶

Working with Assets — managing the assets/ folder specifically
Sharing a Project as a Template — templates as a distribution format
Supported File Types — what can go in which folder

Project Folder Structure¶

Typical project layout¶

File-by-file breakdown¶

main.py¶

README.txt¶

project.json¶

_whittl_launcher.py¶

assets/¶

data/¶

archives/¶