A lightweight Pomodoro timer for the terminal.
potter takes the good parts of browser Pomodoro apps (focus cycles, tasks, streaks, ambient music) and puts them in a single terminal app that's much lighter than a browser tab.
Status: v0.5 β timer, settings, tasks, daily goal, streaks, music and per-task history work.
I use CachyOS + Hyprland + Noctalia Setup and I have a nice ytplay command where I can basically search in YouTube and play things using yt-dlp and mpv. And I think it is one of the most amazing things in my computer. Definitely not exaggerating. Moreover, I split my terminal and open cava and it is an amazing pleasure. And I also love using blanket and termdown and also a nice todos thingy. So, I thought what if we can combine these all to a single terminal app.
- Light. potter is a small native program that barely touches your CPU and uses only a few MB of memory. Music plays through mpv, which needs more while it's playing, but the whole thing still stays far lighter than a browser tab.
- Fits into a riced environment. The background stays transparent, so your terminal's opacity and blur show through. Colors come from the terminal palette by default, so pywal or matugen themes (Noctalia, for example) apply automatically.
- Keyboard-first. Every action has a key, and the mouse is optional.
- Local only. No accounts and no network, except for music you choose to play.
- Accurate time. The countdown is based on end times measured with
CLOCK_BOOTTIME, not on counting ticks, so it doesn't drift and keeps counting while the laptop sleeps.
- Focus, short break and long break phases. The defaults are 25, 5 and 15 minutes, with a long break after every 4 focus sessions.
- A big centered countdown, a phase label, a session counter (e.g.
β β β β) and a progress bar. - Start, pause, reset and skip-phase controls.
- A settings screen inside the app for:
- focus, short break and long break lengths
- how many sessions come before a long break
- auto-starting breaks and focus sessions
- desktop notifications (
notify-send) and a terminal bell when a phase ends - the color scheme: terminal palette (default) or custom hex colors
- Settings are saved to
~/.config/potter/config.toml, and you can edit that file by hand too. - The background is transparent: potter never paints one.
- A to-do list beside the timer that you can add to, rename, complete, reorder and delete.
- One level of subtasks.
- Marking one task as the active task (
βΆ), so focus time is credited to it as it happens. Pauses, resets, skips and breaks don't count. - Per-task time tracking, with subtasks' time rolled up into their parent.
- Tasks are saved to
~/.local/share/potter/tasks.toml, at least every 30 seconds while the timer runs and whenever you change something.
- A daily focus goal in minutes (default 1h 40m, i.e. 4 Γ 25 min). Every focused minute counts, with or without an active task.
- Today's progress and your streak under the timer:
45m / 1h 40m today Β· π₯ 5, plus a notification when you reach the goal. - A streak counts consecutive days that met their goal. Today doesn't break it while it's still in progress.
- A new day starts at 4 AM by default (adjustable), so late-night focus counts for the day before.
- A history view (
h): a vertical bar chart of the last 14 days with the goal line, current and best streak, and totals. - History is saved to
~/.local/share/potter/history.toml.
- A music screen (
m) with one box for everything: type words to search YouTube (top 5 results, pick one with enter), paste a link to play it, or type a file or folder path (~/Music/...) to play local music. - Playback runs through
mpvin the background (audio only), controlled by potter. YouTube needsyt-dlp. - Now playing under the timer: the title,
βΈ 1:23 / 4:05and a progress bar. - Play/pause with
pand volume with+/-from anywhere; the volume is remembered. - Favorites: press
fwhile something plays to save it; replay it from the music screen. Saved to~/.local/share/potter/favorites.toml. - Music pauses during breaks and resumes when focus starts (a setting, on by default). Pausing or playing by hand always wins.
- Music stops when you quit potter.
- potter's mpv doesn't read your own mpv config (
~/.config/mpv), so settings meant for videos can't break music. To configure it, write anmpv.confin~/.config/potter/mpv/(same format as mpv's). Addinclude=~/.config/mpv/mpv.confthere to reuse your own config.
- Your history now remembers which task your focus went to β even after you finish, rename or delete the task.
- In the history screen (
h),β/βpicks a day in the chart and shows where that day's focus went, task by task (plus "no task" time). - A second tab (
tab) shows focus totals per task for the last 7 days, 30 days or all time (rto switch), with each task's status: active, open, done or deleted. - Days recorded before v0.5 keep their totals but have no per-task details.
- Since v0.5.1: select a task in the totals tab and press
ddto remove its time from your history β handy for test runs. Its time also comes off those days' totals.
β/βjump back/forward 10 seconds, and0β9jump to 0%β90% of the track, like on YouTube. Works on the timer screen and in the music screen.- potter remembers where you left off in each track (YouTube, links, files and favorites). Play it again and the music screen offers
you left off at 2:31 Β· press r to resume. The first and last 15 seconds don't count, and live streams aren't remembered. - Positions are saved to
~/.local/share/potter/positions.toml(the newest 200 tracks).
- A sounds screen (
b) with background sounds like in Blanket: rain, storm, wind, waves, stream, birds, summer night, fireplace, coffee shop, city, train and boat, plus white, pink and brown noise. - Mix as many as you like, each with its own volume (
β/β). They play next to your music. - Recordings are downloaded the first time you turn them on (0.1β4.8 MB each, into
~/.local/share/potter/sounds); after that they work offline. The noises are generated live, so they need no download. - Your own sounds: put audio files (
.ogg,.mp3,.flac, β¦) in~/.local/share/potter/soundsand they show up under "Your sounds". - potter remembers each sound's volume and your last mix:
rin the sounds screen brings it back. Sounds start silent when potter opens. - Sounds pause during breaks along with the music (the "Pause audio during breaks" setting).
Bpauses and resumes just the sounds from the timer screen; the music keeps playing (andpstill pauses only the music).- Credits for the recordings: SOUNDS.md.
- Queue: press
eon a search result or favorite to play it after the current track (ortabinstead ofenterto queue a link or path you typed). The queue shows in the music screen:enterplays an entry,ddremoves it,cclears what's up next. </>go to the previous / next track, in the music screen and on the timer screen.- Loop:
lcycles through loop off β loop this track β loop the queue. Kept until you quit potter. - YouTube playlists: paste a playlist link and all of its tracks go into the queue. A link to a video inside a playlist (
watch?v=β¦&list=β¦) plays the whole playlist, starting at that video. - Playing something with
enterwhile a queue exists replaces just the current track; the rest of the queue stays.
- Waybar or Noctalia bar integration, via a
potter statuscommand that prints the remaining time as JSON. - Control from scripts or keybinds (
potter toggle,potter skip) through a small local socket. - A compact mode for a tiny floating terminal window (Hyprland float rule), which works like picture-in-picture.
- Packaging for the AUR.
| Key | Action |
|---|---|
space |
Start / pause |
r |
Reset current phase |
n |
Skip to next phase |
s |
Open settings |
t |
Show / hide the task panel |
h |
History: days, task totals, streaks |
m |
Music screen |
p |
Play / pause music |
< / > |
Music: previous / next track in the queue |
+ / - |
Music volume |
β / β |
Music: back / forward 10 seconds |
0β9 |
Music: jump to 0%β90% |
b |
Sounds screen: rain, waves, brown noise⦠|
B |
Pause / resume sounds (music keeps playing) |
? |
Help |
q |
Quit |
In the task panel: ββ/jk move, a add, A add subtask, e rename, x done, enter make active, dd delete, J/K move down/up.
In the history screen: β/β pick a day, tab switch between days and task totals, r change the totals' range, j/k move, dd remove a task's time from the history, esc close.
In the music screen: / search or paste a link/path (enter plays it, tab queues it), ββ/jk move, tab next section, enter play, e add to queue, </> previous/next, l loop off/track/queue, c clear the queue, p pause, +/- volume, β/β seek 10s, 0β9 jump, r resume where you left off, f add/remove favorite, x stop, dd remove a queue entry or favorite, esc close.
In the sounds screen: ββ/jk move, enter turn a sound on/off, β/β volume, p pause/resume all sounds, r bring back your last mix, x all off, esc close.
In settings: ββ/jk move, ββ/hl change (H/L Β±5), enter toggle or edit a color, esc save and close.
- Language: C++20, with FTXUI for the UI (components, layouts, mouse support).
- CMake downloads FTXUI automatically at build time (
FetchContent), so nothing needs to be installed by hand.
- CMake downloads FTXUI automatically at build time (
- Build: CMake (3.20+) with GCC or Clang.
- Config: TOML at
~/.config/potter/config.toml, read with toml++ (in the Archextrarepo, or fetched by CMake). - Data: tasks, focus history and favorites in
~/.local/share/potter/(following XDG). - Notifications:
notify-send. Music and sounds:mpv(controlled over its JSON IPC socket, parsed with nlohmann/json) +yt-dlp; sounds are downloaded withcurl. All optional at runtime: potter tells you what to install. - Style: modern C++ with RAII, no raw
new/delete, andstd::chronofor all time math.
potter/
βββ CMakeLists.txt
βββ README.md
βββ CHANGELOG.md
βββ src/
β βββ main.cpp # start-up, screen + main loop
β βββ app.hpp/.cpp # glue: app state, key handling, connects everything
β βββ core/ # pure logic, no UI, unit-tested
β β βββ timer.hpp/.cpp # Pomodoro phases + focus meter
β β βββ clock.hpp # a clock that keeps counting during sleep
β β βββ tasks.hpp/.cpp # task list + tasks.toml
β β βββ history.hpp/.cpp # focus per day, daily goal, streaks
β β βββ music.hpp/.cpp # input types, yt-dlp + mpv parsing, favorites
β β βββ sounds.hpp/.cpp # the sound list, volumes and last mix
β β βββ config.hpp/.cpp # load/save config.toml
β β βββ storage.hpp/.cpp # XDG paths + safe file writes
β βββ system/ # talks to the OS and other programs
β β βββ process.hpp/.cpp # starting programs without a shell
β β βββ notify.hpp/.cpp # desktop notifications (notify-send)
β β βββ player.hpp/.cpp # mpv in the background, over its IPC socket
β β βββ search.hpp/.cpp # YouTube search with yt-dlp, in the background
β β βββ sounds.hpp/.cpp # background sounds: downloads + one looping mpv each
β βββ ui/ # everything drawn on screen (FTXUI)
β βββ views.hpp
β βββ timer_view.cpp # timer + help screens
β βββ task_view.cpp # task panel
β βββ history_view.cpp # history bar chart
β βββ music_view.cpp # music screen
β βββ sounds_view.cpp # sounds screen
β βββ settings_view.cpp # settings screen
βββ tests/ # one test program per core module
β βββ timer_test.cpp
β βββ tasks_test.cpp
β βββ history_test.cpp
β βββ music_test.cpp
β βββ sounds_test.cpp
βββ sounds/ # the sound recordings, downloaded by potter on first use
βββ packaging/
β βββ build-static.sh # fully static Linux build (Alpine/musl, run via Docker)
β βββ update-packages.sh # points the AUR files at a new release
β βββ update-formula.sh # points the Homebrew formula at a release
β βββ aur/ # PKGBUILDs: potter (from source), potter-bin
βββ RELEASING.md # release checklist
βββ SOUNDS.md # credits and licenses for the sounds
βββ docs/
Everything in core/ is free of UI and system code, so the logic can be tested on its own. Includes are written from src/, e.g. #include "core/timer.hpp".
- Linux or macOS
- A C++20 compiler (GCC 11+ or Clang 14+) and CMake 3.20+
- Internet access for the first build (CMake downloads FTXUI, and toml++ / nlohmann-json if they aren't installed)
- Optional:
notify-send(libnotify) for desktop notifications - Optional:
mpvfor music and sounds, plusyt-dlpfor YouTube andcurlto download sounds
On Arch / CachyOS:
sudo pacman -S --needed base-devel cmake libnotify tomlplusplus nlohmann-json mpv yt-dlpOn Debian / Ubuntu:
sudo apt install build-essential cmake libnotify-bin mpv yt-dlpbrew install zehraduymaz/tap/potter
brew install mpv yt-dlp # optional, for musicUpdate with brew upgrade potter. On macOS, notifications use the system's own (no notify-send needed).
Coming soon as potter (builds from source) and potter-bin (the static release binary) β AUR sign-ups are closed for now.
The release binaries are fully static: one file that runs on any 64-bit Linux distro β Arch, Debian, Ubuntu, Fedora, openSUSE, old or new β for both x86_64 and ARM64 (e.g. Raspberry Pi), with nothing else to install.
# downloads the newest release for your CPU (x86_64 or aarch64)
curl -L "https://github.com/ZehraDuymaz/potter/releases/latest/download/potter-linux-$(uname -m).tar.gz" | tar -xz
install -Dm755 "potter-linux-$(uname -m)/potter" ~/.local/bin/potter
potter --versionMake sure ~/.local/bin is on your PATH. To update, run the same commands again. Music still needs mpv (and yt-dlp for YouTube) from your distro's packages.
You can also download the files by hand from the Releases page; each one comes with a .sha256 checksum.
potter doesn't run natively on Windows yet, but it works in WSL (Windows Subsystem for Linux). Open your WSL terminal (e.g. Ubuntu) and run the "Any Linux" install commands above. For music, install mpv and yt-dlp inside WSL; sound works out of the box on Windows 11.
git clone https://github.com/ZehraDuymaz/potter.git
cd potter
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/potter
# run the tests
ctest --test-dir build
# install to ~/.local/bin
cmake --install build --prefix ~/.localThe first configure downloads FTXUI (and toml++ if it isn't installed), so it needs internet once.
Built with the help of Claude Code. I designed the features, tested and released it, and I'm learning C++ through it.
potter's mpv doesn't read your own mpv config (~/.config/mpv), only ~/.config/potter/mpv/, so your video settings can't get in the way. If you added include=~/.config/mpv/mpv.conf there, try removing it first.
Common culprits in an mpv.conf:
| Setting | What happens in potter |
|---|---|
mute=yes |
everything plays, but silently |
ytdl=no |
YouTube links and search results don't play |
script-opts=ytdl_hook-ytdl_path=youtube-dl |
YouTube fails if it points to the old youtube-dl β point it to yt-dlp or remove it |
audio-device=... |
no sound if that device isn't connected |
no-audio can't break it: potter always turns audio back on.
Check mpv itself. If this doesn't play in a normal terminal either, the problem is mpv or yt-dlp, not potter:
mpv --no-config --no-video "https://www.youtube.com/watch?v=JCKBaJDRMw4"Extra mpv options go in ~/.config/potter/config.toml, e.g. mpv_args = "--audio-device=auto" under [music]. Run mpv --audio-device=help to list your devices.
YouTube sometimes refuses the audio link yt-dlp hands to mpv (HTTP error 403). potter retries for a few seconds, which fixes the usual case. If it still fails, update yt-dlp (below): YouTube changes often and yt-dlp catches up quickly. To see mpv's real error, run it yourself:
mpv --no-video "https://www.youtube.com/watch?v=dQw4w9WgXcQ"YouTube changes often, and an old yt-dlp stops working. Update it (sudo pacman -Syu yt-dlp, brew upgrade yt-dlp, or yt-dlp -U if you installed it yourself).
potter is free software, licensed under the GNU General Public License v3.0 or later.