Documentation

How it works

Deep Work Lock locks a GNOME desktop on one target until a timer runs out. You choose a duration and a single target: a window, a whole application, or one Chrome or Firefox tab. Until the countdown ends, that is the only thing you can see and use. There is no stop button.

Install

Run this in a terminal, as your normal user:

The command does three things:

1. Loads the GNOME extension from extensions.gnome.org. GNOME asks you to confirm, one click.
2. The extension installs its own bridge to your browsers, in your home folder, with no root.
3. Adds the browser extension to Chrome and Firefox. It asks for your password once; then restart your browser.

Requirements

• GNOME Shell 46, 47, 48 or 49.
• To lock browser tabs: Google Chrome (the .deb from Google) and/or Firefox (the snap, the build from Mozilla's repositories, or the tarball in /opt/firefox or on your PATH). Only the browsers you have are configured.

Running the command again is safe: it updates an existing installation and ends in the same state.

Two consequences of browser policies

• Chrome shows Managed by your organization in its menu for as long as the policy that installs the extension exists. Uninstalling removes it.
• Browser policies live in /etc and apply to every account on the computer, so the browser extension appears for every user. The GNOME lock is installed only for the account that ran the command.

Using it

Click ◉ Focus in the top bar and choose a duration: 25, 30, 45, 60 or 90 minutes, or a value of your own. Then choose a target and click Lock for N min. Chrome and Firefox windows expand to offer their tabs.

During a session

• The top bar and the dock are greyed out and inert, and the countdown shows in orange.
• Alt+Tab, Super, the overview, the hot corner, workspaces and launcher shortcuts are disabled.
• Every other window is minimised. Dialogs belonging to the target stay usable.
• Notifications are turned off.
• Super+L still works, and the time keeps running while the screen is locked.

For a Chrome or Firefox tab:

• New tabs and windows are closed, and focus is forced back to the tab.
• Internal pages are blocked (chrome://, about:addons, about:config, about:debugging…).
• Navigation stays on the tab's host and its subdomains: a lock on docs.google.com does not open mail.google.com or gemini.google.com. The only exceptions are the Google, Microsoft and Apple sign-in pages (accounts.google.com, login.microsoftonline.com…).
• Popups opened by the tab (for sign-in) are allowed, but must stay on those same sites or they are closed.

Behaviour choices

• Target closed: the session continues. A closed tab is reopened on its last address. A closed window leaves an empty desktop; only a window of the same application opened after the lock started can become the new target, and windows that were already open stay hidden. If it was the browser's last window, the browser closes and the desktop stays empty until the end. A new browser window becomes the target only if the extension announces it.
• Firefox restarting by itself (an update): its windows stay hidden until the extension reconnects, finds the locked tab (or reopens it on its last address) and announces its window. In Firefox troubleshooting mode the extension does not run, so the desktop stays empty.
• Browser windows with the same title: they do not offer their tabs in the menu, because there is no way to tell them apart. They can still be locked as windows.
• GNOME Shell restarts: on X11 the session resumes with the time remaining. On Wayland a Shell restart ends your login, so the session ends and your settings are restored.
• The computer restarts: the session ends and every setting is restored at startup.

Known limits

• Ctrl+Alt+F3 (text console) and rebooting get you out. This is intentional.
• Chrome DevTools docked in the tab (F12) cannot be blocked by an extension. Detached into their own window, they are minimised.
• Incognito and private windows: the extension has no access to them, but the desktop lock minimises them.
• The Firefox sidebar (bookmarks, history, AI assistant) is not a tab, so an extension cannot close it.
• If the target is a terminal, gnome-extensions disable remains possible from that terminal.
• Other desktops and other browsers (Chromium, Brave, Flatpak browsers) are not supported.

Troubleshooting

Uninstall

This removes the extensions and the browser policies, and restores your settings if a session was running.

Development

The source is on GitHub. To try a local build, run scripts/dev-install.sh from a checkout; it builds the repository and links the extension into your GNOME extensions folder. npm test runs the test suite.