Skip to content

Dependencies

Only vendor in dependencies and always commit them, always remove from the dependencies what is not needed.

The app

This app allows to create tasks, timers that one can start to and remind the user via system notifications that they should stop the current task and then continue with the next one.

Architecture

Hyperfocus is split into a background service (daemon) and thin clients (a GUI and a CLI). The service owns all task and timer state, so timers keep counting and notifications keep firing even when the GUI is closed.

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

Modules

  • main.rs — entry point. Bare hyperfocus launches the GUI; any argument routes to the CLI.
  • app.rs — egui GUI. A thin client that renders cached state and forwards every action to the service. Polls Status every 250ms while a timer runs.
  • cli.rs — CLI subcommands (add, list, done, remove, clear, service, help). Also a thin client.
  • client.rs — connects to the daemon over a Unix socket, auto-starting it if it is not running.
  • service.rs — the daemon. Holds the task list and timer, ticks the timer once per second, sends notifications on expiry, and persists tasks. Exposes service <start|stop|status>.
  • protocol.rs — shared IPC types (Request, Response, TimerInfo, TimerStatus) and the socket path.
  • storage.rs — JSON persistence of tasks to the XDG data dir.
  • task.rs — the Task model.
  • timer.rs — the timer state machine used inside the service.

Communication

Clients and the service talk over a Unix domain socket (at $XDG_RUNTIME_DIR/hyperfocus.sock, falling back to /tmp). Each request/response is a single line of JSON. Both the GUI and CLI auto-start the daemon on first use.

Tasks

Use mise for common workflows:

  • mise run run — build and run the app.
  • mise run format — apply cargo fmt and cargo clippy --fix.
  • mise run verify — format check, tests, and clippy with -D warnings.