Skip to content
akshit-python-programmerPublic

About

Calm, ADHD-friendly day planner built with pygame. Visual timeline + nested todos + focus timer.

Topics

Resources

Contributing

Stars

23 stars

Watchers

1 watching

Forks

Repository files navigation

Foci — calm, ADHD-friendly focus calendar

A day-planner, to-do list, and focus timer in one quiet window. Built to make starting the day feel manageable instead of overwhelming.

Python pygame Platform License CI Contributions welcome


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 :

  1. added new themes cafe,peach on requuest of Shaurya
  2. Implemented keyboard shortcuts on request of fazal.
  3. going to add proper google calendar integration on request of Anaconda_bro.
  4. fixed audio glitches bugs pointed out by shagun.

Screenshot

Foci main view

Demo

Calendar & event drag Focus timer
Calendar view Focus timer
Theme switcher Confetti & drag-reorder
Themes Confetti

Full walkthrough → demo/demo.mp4


Install & run

# 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.py

To try just the standalone focus timer:

python progress.py

Run the tests

pip install pytest
pytest -q

Build a standalone .exe

pip install pyinstaller
pyinstaller main.spec
# output: dist/Foci.exe

Optional: Google Calendar sync

  1. In Google Cloud Console, create an OAuth 2.0 Desktop client and enable the Calendar API.
  2. Download credentials.json → place it in your data folder (assets/ when running from source).
  3. 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.py can 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.


Tech stack

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

Features

Day timeline

  • 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

Event editor

  • 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

Nested to-do list

  • 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)

Focus timer

  • 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

Lofi music player

  • 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

Themes & fonts

  • 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 / .otf and previews them live (ships with Domine, Roboto, Arimo, SansCode, RobotoCondensed)

Gamification & feedback

  • 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

Stats

  • Animated donut charts (ease-out cubic) showing tasks completed % and time focused % for the day

Keyboard shortcuts

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

Weekly view

  • 7-column overview with event cards per day; click a day to jump to it; today column is highlighted

Settings panel

  • 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

Local-first & privacy

  • 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.json templates are included
  • Nothing is uploaded anywhere

Optional: Google Calendar sync (experimental)

  • google_calendar.py — standalone OAuth2 flow using google-api-python-client
  • Bring your own credentials.json from Google Cloud Console; token is stored locally and never committed

Your data

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.


Acknowledgements

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

Contributing

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.


What I learned

  • 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.Process so 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

License

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.

About

Calm, ADHD-friendly day planner built with pygame. Visual timeline + nested todos + focus timer.

Topics

Resources

Contributing

Stars

23 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages