Basic Usage:

Just start the pomodoro and give it a meaningful name! Pomodoro will notify its various states, using both growl and spoken alerts. When Pomodoro is finished, you can change the description in the Stats/Backlog panel if you like. If you want a better integration with your daily workflow, use the Applescript tab to write your own actions. You can also notify your friends using the Twitter tab.
In one of the next releases I'll bundle useful Applescripts: if you developed something useful and want to share, let me know

You'll need to install Growl Framework separately if you want growl notifications. It's a simple install and a lot of other mac software is Growl enabled. Highly recommended.

You can start/stop and interrupt/resume the pomodoro using only the keyboard, and customize keyboard shortcuts as needed.

Volume Control:

You can control separately the volume of speech, ringing and ticking sounds in the Setup, general tab.
Pomodoro behaviour

In the Setup panel you can control pomodoro behaviour:

  • Pomodoro duration, in minutes. Default is 25 minutes.
  • Handled interrupt duration: the amount of seconds the pomodoro can be interrupted without being automatically voided. Default is 15 seconds.
  • Ask pomodoro name: If set to NO, you'll only be able to change pomodoro names in the Backlog window. Default is YES, meaning pomodoro will start only after giving a meaningful name
  • Automatic pomodoro restart: at the end of the break, pomodoro will automatically restart. Default is NO
  • Ring alarm when Pomodoro ends: a ringing sound will notify of pomodoro ending. Default is YES. You can control the volume, too: default volume is 100% of system volume.
  • Ticking sound: a tic-tac sound. Default is YES, and the default volume is 20% of system volume.
  • Break: start a break when pomodoro ends. Default is YES, and default break duration is 5 minutes.
  • If break is enabled, you can configure the pomodoro to have a longer break every four pomodoros done. Default is YES, and default break duration is 10 minutes.
  • Break ring alarm when Pomodoro ends the break: a ringing sound will notify of pomodoro ending. Default is YES. You can control the volume, too: default volume is 100% of system volume.
  • Ticking sound during break disable it if you want breaks behave differently than working time. Default is YES.
  • Can restart during breaks you shouldn't start a new pomodoro if you hadn't rested for a while, but a lot of people asked for it, so here it is. Default is NO.
  • Synthesized voice: you can choose here the voice used to notify pomodoro events (if enabled). Default is Alex, and default volume is 80% of system volume.
Customizing notifications:

Every growl/speech/twitter/applescript notification can be enabled/disabled and personalized to your needs.

Events are the same for all categories: only twitter notifications are limited to a subset. Growl start can be selected to be sticky, as a visual clue for the user.
In all kind of notifications textfields (Growl, Speech, Twitter and Applescript) you can use $pomodoroName and $duration placeholders to indicate current name and current duration.

In Interrupt notifications text, you can also use $secs placeholder to indicate the interrupt duration.
In "Every" notification text, you can also use $mins, $passed and $time placeholders to indicate respectively interval time, total time passed and how much time is left.
Default values for preferences:

To reset default values, use the "Reset back to default values" button in Preferences panel (twitter user/pwd will be preserved) or just type this commands on your shell (twitter user/pwd won't be preserved):

cd
rm Library/Preferences/com.ugolandini.pomodoro.plist


or just:

rm ~/Library/Preferences/com.ugolandini.pomodoro.plist

(the ~ character means your home dir: if it's not on your keyboard you can usually get it by pressing alt-5)

Session stats and Backlog (Database of pomodoros)

The Stats window shows session information for your pomodoro (memory only) and a full backlog (persistent to disk). The backlog contains the description you gave initially (if disabled, the last one) and the date/time of delivery.

You can delete pomodoros with the Delete button.


Backlog managing and troubleshooting

The sqlite DB of pomodoros is here:

~/Library/Application Support/Pomodoro/Pomodoro.sql

That means you can for example export the entire pomodoros backlog in a CSV (Comma Separated Values) file with a simple oneliner terminal command:

echo 'select * from zpomodoros;' | sqlite3 -csv ~/Library/Application\ Support/Pomodoro/Pomodoro.sql > pomodoros.csv

you can also delete it if you have problems (it will be automatically recreated at the pomodoro start), or try to edit directly with the command (not recommended):

sqlite3 Pomodoro.sql
Twitter notifications

You can notify your friends of your daily pomodoro workflow using the twitter tab integration. Just enable it, insert your username/password, optionally check your connection to twitter services and customize the twitter messages. If you don't own a twitter account or simply don't know what twitter is (where were you living? in a cave?) check the Twitter link and register for a free account.
Applescript notifications

Pomodoro can be fully integrated in your daily pomodoro workflow: every notification can be associated with an applescript script.

You can for example stop your messenger software, listen to your favourite song with itunes or whatever action you feel appropriate. Some examples can be found here. If you will develop you own scripts, just remember to name the scripts *.pomo or they won't be selectable.

See the Apple page for further details on applescript.
Shortcut customisation

Pomodoro can be fully managed using only the keyboard. You can also customize pomodoro shortcuts easily in the shortcut panel
Feedback (bugs, improvements, requests for new features) is welcome.