Desktop Pomodoro Timer

Project roadmap

1. 01

   Define the settings and screens

   ~1h

   Write README.md: the settings (work, short break and long break lengths, sessions before a long break, and sound on or off) with allowed ranges, the keys (Space to pause and resume, S to skip, Q to quit), what the screen shows, and the history file format. Create a project with dotnet new console. Done when: README.md describes the settings, keys and files.

2. 02

   Model settings and history

   ~1h

   Create a Settings record with validation of each value, and a Session record (type, start, end, and completed or skipped). Load and save both as JSON with System.Text.Json in the user's application data folder, creating defaults when the file is missing and falling back to defaults with a warning when it's invalid. Done when: settings and history are saved and loaded correctly.

3. 03

   Build the timer

   ~2h

   Write a PomodoroTimer class that tracks the current phase and the remaining time using the real clock (a Stopwatch or DateTime.UtcNow) rather than counting ticks, so it stays accurate. It supports pause, resume, skip, and moving to the next phase, with a long break after every Nth work session. Take the clock as a parameter so tests can control time. Done when: unit tests with a fake clock show correct phases and remaining times.

4. 04

   Draw the countdown and handle keys

   ~2h

   In the main loop, redraw the screen a few times per second without flicker (moving the cursor with Console.SetCursorPosition instead of clearing): the phase name, a large mm:ss countdown, a progress bar and the session count. Check for key presses with Console.KeyAvailable and Console.ReadKey(true), so the loop never blocks. Beep (Console.Beep, where supported) at the end of each phase. Done when: the countdown runs smoothly, and all keys work.

5. 05

   Show statistics

   ~1h

   Record each finished or skipped session in the history, and add a stats command-line option that shows today's and this week's completed work sessions and total focus time, and the longest streak of days with at least one session. Done when: the statistics match the history file.

6. 06

   Test it

   ~1.5h

   Write xUnit tests for the timer with a fake clock (phases, pause and resume, skip, and the long break rule), settings validation, loading broken JSON, and the statistics calculations. Done when: dotnet test passes.

Resources

• DocsSystem.Text.Json overview
• DocsConsole class
• DocsStopwatch class
• ArticlePomodoro Technique (Wikipedia)
• DocsUnit testing C# with xUnit