Terminal Chess Clock
Build a chess clock that runs in the terminal in C++: two timers, one per player, where pressing a key ends your turn, stops your clock and starts your opponent's. You choose the starting time and an optional increment (extra seconds added after each move, as in 5+3 blitz), and you can pause and resume. The clocks count down live on screen, show the number of moves, and announce when a player's time runs out. It's a fun first C++ project: you'll learn classes, measuring time precisely with std::chrono, reading keys without waiting for Enter, updating the screen in place, and testing time-based code with a fake clock.
- Estimate
- ~8h
- Steps
- 6
- Completed by
- 0
- Proposed by
- codeseed.app
CMake · std::chrono · termios
Project roadmap
- 01
Define how it works
~0.5hWrite README.md: the command (chessclock 5+3, meaning 5 minutes plus 3 seconds per move), the keys (Space ends the current turn, P pauses and resumes, R resets and Q quits), what the screen shows, and what happens when time runs out. Set up a CMake project. Done when: README.md describes the time format, keys and screen.
- 02
Write the Clock class
~2hWrite a Clock class holding each player's remaining time as std::chrono::milliseconds, whose turn it is, the move count, and whether it's paused. Give it a function that takes the current time from an injected clock source, so tests can control time: switch_turn() subtracts the elapsed time from the current player, adds the increment, and switches players. Done when: unit tests with a fake clock show time is subtracted and the increment added correctly.
- 03
Parse the time setting
~1hParse settings like 5+3, 10+0 and 3 (minutes plus seconds increment) from the command line, with a clear error for invalid formats, negative numbers or times over 3 hours. Done when: valid settings are parsed and invalid ones print a helpful message.
- 04
Read keys and update the screen
~2hPut the terminal in a mode where single key presses are read without Enter and without echo (termios on Linux and macOS, _getch on Windows), and restore it on exit, even on Ctrl+C. In the main loop, check for a key, update the clock, and redraw both times (mm:ss, and tenths of a second under 10 seconds) about 10 times per second, highlighting the active player. Done when: the clocks count down live, and pressing Space switches them.
- 05
Handle pausing and time running out
~1hPausing stops both clocks and shows PAUSED; resuming continues without losing or gaining time. When the active player's time reaches zero, stop the clock and announce who lost on time and the number of moves. Ignore key presses after the game ends, except R and Q. Done when: pausing is accurate, and a flag fall is announced correctly.
- 06
Test it
~1.5hWrite tests (for example with doctest or Catch2) using the fake clock: turns and increments, pausing and resuming, time running out exactly, parsing settings, and time formatting. Done when: all tests pass.
Resources
Ready to build this?
Get a GitHub repo and start building. Your AI reviewer checks each step as you go.
Tech stack