Skip to content

Your First Project

This page walks you from a fresh Whittl install to a running generated app. About five minutes. It assumes you have installed Whittl and set up at least one backend.

The first time you open Whittl, a short tour points out the parts of the window. Its last two steps let you choose the picture and name shown beside your own messages in the chat, and say where to find help. Help > Show Welcome Tour runs it again.

Create the project

Click + New in the Projects panel on the left (or File > New Project, Ctrl+N). The New Project dialog asks one question first: what are you building? Desktop app, Simple desktop app, Mobile app, Plugin (a tool or panel for Whittl itself) or Just Python (a script, no window).

Pick Desktop app. The second screen asks for a name and whether to start Blank or from a Template for that kind of project. Name it "todo", leave Blank selected, and click Create.

Whittl creates a project folder at ~/.whittl/projects/todo_<random_id>/, opens main.py in the code editor, and puts you in the chat.

Why the random ID

Each project folder ends in a short random code (todo_27176a00) so two projects with the same name do not collide. The sidebar shows the name; the code is used internally.

Generate the first version

In the chat, type:

Make me a simple todo list app. The user can type a task in a text box, hit Enter or click Add, and the task appears in a list below. Each item has a checkbox to mark it done and an X button to remove it. Save the list to a JSON file in the project folder so it persists between runs.

Press Enter to send (Shift+Enter adds a line), or click the send button beside the box.

What happens, in order:

  1. Whittl decides what kind of request this is: a new app, a change, or a question.
  2. Skills join the prompt. Whittl's skill library adds PySide6 guidance: signals, list widgets, the threading mistakes to avoid.
  3. The AI writes the code, and it streams into the editor as it is written. A model that calls tools builds file by file, checking the syntax and running the app as it goes, and every step shows as a line in the chat.
  4. Pattern fixes run. Whittl's rules catch common mistakes (wrong Qt enums, missing imports) on the way into the editor.
  5. A quick test runs. Whittl starts the app invisibly for a few seconds to catch a crash on launch. If it crashes, auto-fix starts on its own.

On a cloud backend, a small app like this typically takes 10 to 30 seconds. On Ollama, 30 seconds to several minutes, depending on the model and your hardware.

Review the generated code

When it finishes, the editor shows the result. For the todo prompt you will typically see one main.py with:

  • A QMainWindow subclass as the app's window
  • A text box and an Add button for new tasks
  • A list of tasks, each row with a checkbox, a label and an X button
  • Helpers that read and write todo.json in the project folder
  • The if __name__ == "__main__": lines that start the app

Skim it. You do not need to understand every line to run it, but knowing how the app is laid out makes follow-up prompts more precise.

Run it

Click Test Run at the bottom of the editor (or press F5). Whittl installs any packages the code imports into its own Python, writes the project's files, and starts the app.

The todo app's window appears. Type a task, press Enter, watch it appear. Tick the box, remove a task, close the window. Click Test Run again: your list is still there.

If the app crashes, the error appears in the Terminal tab and auto-fix makes one attempt to repair it (with AI Auto-Fix Errors on, the default).

Iterate

Say the tasks are hard to read. In the chat:

Make the task text bigger and add a bit of padding between items.

This time Whittl sees a change to existing code. The AI reads what it needs and edits only the lines that matter, and the chat shows each step:

→ Reading main.py
   148 lines
→ Editing TodoWindow.add_task() in main.py
   Edit applied to main.py.

The editor updates in place. Click Test Run again and the app restarts with the change.

A small change like this typically costs a fraction of a cent on a cheap model, far less than writing the whole file again.

Build an executable

When you are happy with the app, turn it into a standalone .exe (Windows) or AppImage (Linux):

  1. Click Download (F3) at the bottom right.
  2. The Build Executable dialog opens. Leave the defaults (or pick an icon) and click Build.
  3. Whittl bundles your code, Python and every package the app needs into one file. It takes one to three minutes.
  4. When it is done, the output folder opens. You have an app to share.

The result runs on its own: send it to someone without Python or Whittl and it starts.

Where to go from here