Hyperfocus

A focus timer and task manager. Create tasks with durations, start a timer, and get a system notification when it is time to stop and move on to the next task.

Hyperfocus runs as a background service with two thin clients — a GUI (built with egui) and a CLI. Because the service owns all state, your timer keeps counting down and still notifies you even after you close the window.

Architecture

flowchart TD
    GUI[egui GUI - app.rs]
    CLI[CLI - cli.rs]
    Client[Client - client.rs]
    Service[Service daemon - service.rs]
    Store[tasks.json - storage.rs]
    Notify[System notification]

    GUI --> Client
    CLI --> Client
    Client -->|Unix socket JSON| Service
    Service --> Store
    Service -->|timer expiry| Notify

The GUI and CLI never touch state directly; they send JSON requests over a Unix socket to the daemon, which manages tasks, runs the timer, persists to disk, and fires notifications. Either client auto-starts the daemon on first use.

Usage

GUI

hyperfocus

Running with no arguments opens the window: add tasks on the left, select one, and use Start / Pause / Resume / Stop. When a timer finishes you are notified and offered the next task.

CLI

hyperfocus add "Write report" 25   # add a task (minutes optional, default 25)
hyperfocus list                    # list tasks
hyperfocus done 1                  # mark task 1 completed
hyperfocus remove 1                # remove task 1
hyperfocus clear                   # remove all completed tasks

Service

hyperfocus service start           # run the daemon in the foreground
hyperfocus service stop            # stop the daemon
hyperfocus service status          # check whether it is running

Development

This project uses mise for tasks:

mise run run       # build and run
mise run format    # cargo fmt + cargo clippy --fix
mise run verify    # format check, tests, and clippy (-D warnings)