BUILD AN APP

Build with an AI assistant

Most apps get written by an assistant. Point yours at these files and describe what you want to track. Each one covers the whole format, so the model doesn't have to guess.

Rather write it yourself, or want to understand what the assistant wrote? Read the app docs: every block, with a live example.

/llms.txtShort indexWhat an app is, the rules, and links, in plain markdown.Open

/llms-full.txtFull referenceEvery block, computed value and hook, with complete examples and common mistakes. One paste.Open

pomodoso-plugin/SKILL.mdAgent skillFor Claude Code and other agents: writes the file, checks it, fixes errors, and bumps the version.Get the skill

/schema/plugin.v1.jsonJSON SchemaAutocomplete in your editor. Models can check their output against it.Open

Starter prompt

Write a Pomodoso plugin: one YAML file that becomes a small app inside Pomodoso.

What I want it to do: <describe what you want to track or keep>

Before writing, read https://pomodoso.com/llms-full.txt and use only the blocks, field types and computed values it lists. Start from the closest of its examples. Write the whole file, then check it with `npx @pomodoso/plugin validate <file>` (or against https://pomodoso.com/schema/plugin.v1.json) and fix every problem it reports. Give me the final file and a short summary of what it shows and stores.

"Prompt + full reference" is for assistants that can't open links: it pastes the whole reference with the prompt.

The Today widget is opt-in, declared in the file

An app always gets its own screen under Apps. It can only appear on Today if its file has a today block, and even then the user chooses whether to turn it on. Hooks add a question during breaks or the next day, and lines to the reports.

today:
  default_on: true          # suggested; the user can turn it off
  widget:
    type: mini-counter
    label: Cigarettes
    value: $today
    max: $limit
    adds: cigarette         # the +1 button

hooks:
  - on: pomodoro_end
    ask: Did you smoke during this break?
    yes: { add: cigarette }
  - on: weekly_report
    line: "{$week_count} cigarettes ({$week_delta} vs last week)"

Check it, then install or publish

Paste the file into Pomodoso: in the extension, Apps → Add an app → From a file, or in your dashboard → Apps to publish it. Both run the same checks as the directory, say exactly what to fix, and show the app before anything is saved. To check and try a file without installing it, use the validator.

Or from a terminal, with the same validator. It's what agents run to fix their own mistakes:

npx @pomodoso/plugin validate my-app.yaml