FocusGuard
Vigi, the FocusGuard mascot
Arch Linux + Hyprland

A real, enforced
focus mode, guarded by Vigi

Pick apps in a native GTK4 window. Schedule them, or block them on the spot. A background daemon actually stops them from running. No root required.

View on GitHub Install instructions
License Python 3.11+ Tests 
$ focusguardctl vigi

     .-------.
    /  o   o  \
   |     ‿     |
    \_________/
       Vigi

  Vigilance intensifies.

# a block that actually blocks
$ focusguardctl start School
ACTIVE - blocking 4 app(s)
  School               ACTIVE
Meet the mascot

Vigi is always on watch

A small shield who blinks, glances around, waves, and shows up the moment a blocked app gets caught, not a nag, just a friendly redirect.

Vigi

She reacts to more than just blocking

In the optional Quickshell bar widget, pixel-art Vigi keeps tabs on what's actually happening on your screen, independent of whether FocusGuard is blocking anything.

  • 🎵 Music grooves faster when any MPRIS player is playing
  • 👀 Alert flashes amber and shakes when a distracting app is focused
  • 😳 Stressed turns pink and blinks fast when your CPU is under load
  • 😴 Asleep eyes shut, motion stops, after the screen's been idle a while
  • 🐾 Petting left-click for a wiggle and a random reaction line
What it does

Everything a focus mode should be

Not a honor-system timer. Not built for a desktop you're not running.

🖥️

Native GTK4 + libadwaita

Not a web page in a window. A real, polished Linux desktop app.

🔍

Real app discovery

Via Gio.DesktopAppInfo, with icons, search, Select All / Clear All.

📅

Schedules

Days of week, start/end time, correctly handles windows that cross midnight.

⚡

Manual sessions

"Start School now for 45 minutes" from the GUI or CLI, no schedule needed.

🧩

Multiple profiles

School, Study, Gaming, Bedtime, each with its own apps, schedule, and duration.

⏸️

Explicit override

Pause 5 min, Stop Mode, or Resume: visible, deliberate, never a silent bypass.

🔔

Desktop notifications

On block start/end, with a friendly nudge line from Vigi, throttled per app.

⌨️

Hyprland keybind ready

A scriptable CLI: you choose the key, nothing touches your Hyprland config.

🔒

No root, ever

Runs entirely as your user, with a locked-down socket and protected processes.

The GUI

See what's blocked, at a glance

Status, controls, and profiles, all in one clean window.

FocusGuard main window
Why not an existing tool?

Timers don't enforce anything

ToolWhy it doesn't fit
Timekpr-nExTManages session time budgets, no concept of blocking individual apps while you're logged in.
MalcontentBuilt around Flatpak's permission store and GNOME session services, a poor fit for a minimal Hyprland setup.
cgroups aloneCan throttle a process group but can't stop a new one from launching without root + a BPF LSM filter.

So FocusGuard does what this class of tool has always done on Linux without root: a fast poll-and-kill loop over /proc, matched against exact executable signatures.

Get started

Install on Arch Linux

Two ways in, pick whichever fits your workflow.

# dependencies sudo pacman -S python python-gobject gtk4 libadwaita # build + install git clone https://github.com/rusty-workshop/focusguard.git cd focusguard makepkg -si # enable the daemon systemctl --user daemon-reload systemctl --user enable --now focusguard.service
# dependencies sudo pacman -S python python-gobject gtk4 libadwaita # install git clone https://github.com/rusty-workshop/focusguard.git cd focusguard pip install --user . # then install the systemd unit + desktop file -- # see the README's Installing section for the full steps

Full README → with configuration docs, CLI reference, Quickshell/Waybar widgets, and security notes.