Focus Blocks

A CLI program for implementing Focus Blocks in your daily life.

Intro

Focus Blocks is my take on time management inspired by Flow State, Pomodoro Technique, Timeboxing, and Deep Work. Please read the Introduction to Focus Blocks first to understand the motivation for the creation of this program.

fob is a simple CLI program that lets you plan your month, and then visualize & update your progress within the Focus Blocks time management framework.

It is written in Python with minimal dependencies and can be installed on Mac, Linux, and Windows.

Quick Start

First, install uv (directions here)

Install the required version of python:

uv install python 3.12

Install Focus Blocks:

uv tool install focus-blocks

Warning

Common mistake: The package name is focus-blocks, not fob. Do not do this: uv tool install fob

Now, the fob program is available from anywhere on the system. Try:

fob help

Upgrade

Upgrading focus-blocks doesn't affect the database, so this is safe.

uv tool upgrade focus-blocks

Uninstall

uv tool uninstall focus-blocks

A Day in the Life

It's the beginning of a new month - let's set our goals.

It's a new day! Say good morning!

Check off the first block of the day:

Let's remind ourselves what the day ahead looks like:

Oops, we couldn't do block 3. Let's change that block to 'Buffer', which is exactly for unforeseen things like this.

Checking off the final block for the day. Great job.

Come back tomorrow and say good morning to repeat.

Additional Features

Cloud Sync

Bring your own cloud.

fob runs on a single database file. You can store this database on Dropbox or your own cloud. Just pass the path to the --database option when running fob. For example:

fob --database /home/tensorturtle/Dropbox/my-fob.db help

For more convenience, you can export a FOB_DB_PATH variable in your shell. For example, add the following line to ~/.bashrc (for bash shell):

export FOB_DB_PATH="/home/tensorturtle/Dropbox/my-fob.db"
source ~/.bashrc

Development

Install uv.

Clone this repository:

git clone https://github.com/tensorturtle/fob.git

Run fob without installing it by using uv run:

uv run fob help

Run app in debug mode:

uv run fob --debug

Use database at custom path:

uv run fob --database ~/Downloads/testing_fob.db

The so-called database is actually just a human-readable JSON file. To see its location:

uv run fob info

Testing

uvx pytest

This is an end-to-end test. It installs fob to a temporary directory using install.sh and runs commands against it. Github Actions is set up to run the same test upon pushing to main branch.

Distribution

Update version number in pyproject.toml and utils/utils.py

Build and publish package to PyPI:

rm -r dist/
uv build
uv publish --token $TOKEN

Wait a moment for PyPI database to be updated (maybe a minute) and run:

uvx --from focus-blocks@latest fob

Database Versioning

This package uses SemVer, with an additional convention:

Releases with the same major-minor (0.0.X) version share the same database schema. If a new major-minor version is released, a new database is created and no migrations occur. The old database is not deleted.