A day-planner, to-do list, and focus timer in one quiet window. Built to make starting the day feel manageable instead of overwhelming.
foci.akshitkumarlall.com Foci is a desktop planner I built for myself because most productivity apps felt loud and punishing. It puts a visual hourly timeline, a nested to-do list, and a focus timer side by side — with calm themes, optional lofi music, and small rewards for finishing things. Inspired by tools like Tiimo and Llama Life, but built from scratch with no UI framework.
Recent Updates :
- added new themes cafe,peach on requuest of Shaurya
- Implemented keyboard shortcuts on request of fazal.
- going to add proper google calendar integration on request of Anaconda_bro.
- fixed audio glitches bugs pointed out by shagun.
| Calendar & event drag | Focus timer |
|---|---|
![]() |
![]() |
| Theme switcher | Confetti & drag-reorder |
|---|---|
![]() |
![]() |
Full walkthrough → demo/demo.mp4
# 1. Clone
git clone https://github.com/akshit-python-programmer/Foci.git
cd Foci
# 2. Create a virtual environment (recommended)
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Run
python main.pyTo try just the standalone focus timer:
python progress.pypip install pytest
pytest -qpip install pyinstaller
pyinstaller main.spec
# output: dist/Foci.exe- In Google Cloud Console, create an OAuth 2.0 Desktop client and enable the Calendar API.
- Download
credentials.json→ place it in your data folder (assets/when running from source). - First run opens a browser to authorize; the token is stored next to it as
token.json.
Both files are git-ignored and must never be committed.
Status: experimental.
google_calendar.pycan pull a day's events from Google, but it isn't wired into the app's UI yet and pushing local changes back to Google isn't implemented. See the open issues if you'd like to help.
| Layer | Choice |
|---|---|
| Language | Python 3.10+ |
| Rendering & input | pygame 2 + pygame.gfxdraw |
| UI paradigm | Hand-built immediate-mode GUI (no framework) |
| Audio | pygame.mixer (mp3/wav playback, fade, seek) |
| System media keys | WinRT winrt.windows.media (SMTC) |
| Persistence | JSON (local flat files) |
| Packaging | PyInstaller (main.spec) → standalone .exe |
| Calendar sync (optional) | google-api-python-client + google-auth-oauthlib |
- Drag on the hourly grid to create events; drag events to move them, drag the bottom edge to resize
- Overlapping events auto-layout into side-by-side columns
- Animated red "current time" line with a pulsing comet head scrolls through your day
- Per-hour background shifts from dawn tints → midday → golden hour → night based on actual clock time
- Day progress bar at the bottom fills as the day goes on
- Modal dialog with animated slide-in
- Date picker (navigate days), time picker (hour/minute in 15-min steps), duration slider
- Color picker (5 theme-matched swatches) and icon picker (30 Lucide SVG icons: brain, atom, code, rocket, trophy, and more)
- Edit or delete existing events; editing can move an event to a different date
- Flat tasks and collapsible folders (e.g. Physics → Kinematics → today's problems)
- Date tags: Today, Tomorrow, on Mon. Shown as a pill on each to-do (red when overdue) and rolled forward automatically each day, including to-dos inside folders
- Drag a to-do onto the timeline to turn it into an event (drag-to-reorder within the list is not implemented yet)
- Right-click context menu to schedule a task (Today / Tomorrow / Someday)
- Delete completed tasks in bulk with one button (including ones inside folders)
- Click the ▶ button on any currently-active event to open a standalone focus timer popup
- Large MM:SS countdown with a green progress bar; Space or the button to play/pause
- Separate circular progress arc in the sidebar tracks the current event in real time with a rotating "bean" knob
- Launches as a separate frameless subprocess window (doesn't block the main app)
- Playlist view, play/pause/prev/next/shuffle, volume and seek scrubbing
- Three adaptive layouts: full (playlist visible), compact, and micro (controls only)
- Draggable titlebar via native Win32
ReleaseCapture/SendMessage - Windows SMTC integration — registers with the system media flyout so track name appears in the tray and media keys (⏯ ⏭ ⏮) work system-wide
- 11 built-in themes: Serene Morning, Golden Hour, Midnight Deep, Cyberpunk Night, Forest Canopy, Classic Light, Classic Dark, Kyoto Spring, and new in this release Ocean Breeze, Lavender Dusk and Matcha Latte (suggested by Anaconda bro)
- Several themes feature animated slow-wave gradient backgrounds
- Font picker scans
assets/for any.ttf/.otfand previews them live (ships with Domine, Roboto, Arimo, SansCode, RobotoCondensed)
- Earn coins when you complete an event (1 coin per 5 min of duration); lose them if you uncheck
- Animated coin sprite on each event card shows coins at stake
- Confetti particle burst (80 particles, physics-based) on event completion
- Motivational quote toasts with glassmorphism blur and slide-in animation on to-do completion
- Ding sound effect on check-off
- Animated donut charts (ease-out cubic) showing tasks completed % and time focused % for the day
Suggested by Fazal. Press ? in the app to see them all.
| Keys | Action |
|---|---|
| ↑ ↓ or K J | Select previous / next to-do (walks into open folders) |
| Space / Enter | Check off the selected to-do, or open / close a folder |
| 1 2 3 | Schedule for Today / Tomorrow / Someday |
| N | New to-do |
| Delete | Delete the selected to-do |
| Esc | Clear the selection |
| ← → | Previous / next day (week, in weekly view) |
| Home | Jump to today |
| W | Toggle weekly view |
| S | Today's stats |
| T | Next theme |
| ? / H | Show the shortcuts overlay |
- 7-column overview with event cards per day; click a day to jump to it; today column is highlighted
- Scrollable modal: theme picker (shows each theme's actual colors as a preview), font picker, day start/end hour sliders, calendar zoom slider (30–80 px/hr), sound effects toggle, confetti toggle, lofi toggle
- All data lives in plain JSON files on your machine:
events.json,todos.json,settings.json,player_data.json - Personal files are git-ignored;
*.example.jsontemplates are included - Nothing is uploaded anywhere
google_calendar.py— standalone OAuth2 flow usinggoogle-api-python-client- Bring your own
credentials.jsonfrom Google Cloud Console; token is stored locally and never committed
| File | Contents |
|---|---|
settings.json |
Theme, day hours, zoom, toggles |
todos.json |
To-do list and folder tree |
events.json |
Scheduled calendar events |
player_data.json |
Coin count |
Where they live:
| How you run Foci | Data folder |
|---|---|
From source (python main.py) |
assets/ in the repo |
| Packaged app on Windows | %APPDATA%\Foci |
| Packaged app on macOS | ~/Library/Application Support/Foci |
| Packaged app on Linux | $XDG_DATA_HOME/Foci (default ~/.local/share/Foci) |
Any, with FOCI_DATA_DIR set |
that folder |
The files in assets/ are git-ignored. Copy an *.example.json to get started, or just run the app and it creates fresh files. Corrupt or hand-edited files are repaired field by field on load instead of crashing the app.
Thanks to the people who've shaped Foci with their ideas:
- Fazal: suggested keyboard shortcuts for getting around tasks quickly
- Anaconda bro: suggested the Ocean Breeze, Lavender Dusk and Matcha Latte themes
Bug reports, ideas and pull requests are welcome. See CONTRIBUTING.md for setup, the project layout and how to run the tests. Changes are tracked in CHANGELOG.md.
- Designing calm, focus-supporting UX — color palettes, pacing, and reward loops that reduce friction rather than adding pressure
- Building a custom immediate-mode GUI from scratch in pygame: layout, clipping, scrolling with physics, drag-and-drop hit-testing, and resize interactions with no framework
- Multiprocessing — the lofi player runs as a separate
multiprocessing.Processso it never blocks the main event loop - WinRT / Windows SMTC integration — registering a Python app with the system media transport controls so it behaves like a real media player
- Sprite-sheet animation, smooth gradients, per-pixel alpha overlays, and glassmorphism effects in pygame
- Local-first data design with resilient JSON loading (graceful defaults, malformed-file recovery)
- Packaging a Python app as a standalone Windows executable with PyInstaller
MIT — see LICENSE.
Bundled third-party assets (Domine font, Lucide icons under ISC, lofi tracks) retain their own licenses; see the license/readme files in their subfolders.




