Caffeine toggles GNOME auto suspend from the quick settings menu

A quick settings switch for auto suspend

Caffeine is a GNOME Shell extension whose whole job is one switch: keep the machine awake while you are doing something, then let the screen blank and the session suspend again. The repository description says it disables the screensaver and auto suspend, and the README states it more narrowly as enabling or disabling auto suspend with a quick settings toggle.

The audience is anyone whose machine sleeps at the wrong moment. Presentations, long builds, a video call, or a debugging session where you want to step away from the keyboard are the ordinary cases. It is a desktop convenience for GNOME specifically, not a general power management tool, and the README notes it is published on the GNOME Extensions site.

The interaction model is short. A toggle in the quick settings menu flips the state, a notification confirms the change, and the panel indicator changes appearance so you can read the state at a glance without opening the menu. There is also a timed mode, which turns Caffeine on for a set amount of time rather than leaving it on indefinitely.

The scope is deliberately narrow. The extension does not manage battery profiles, does not change the display's brightness or power draw, and does not touch per-application behaviour. It changes one thing, and it does it from a place you can reach in one click, which is exactly why it is worth having as a separate extension rather than a setting.

Support is split into one branch per Shell generation

The version table in the README is the most important part of the documentation, and it is easy to skim past. The extension supports GNOME Shell 3.4 up to 51, but not through a single code path. Instead, the compatibility lives in parallel branches, each pinned to a range of Shell versions.

The master branch carries extension version 61 and covers GNOME 45 through 51. A branch named gnome-shell-43-44 carries version 51 and covers GNOME 43 and 44. The gnome-shell-40-42 branch carries version 42 for GNOME 40 to 42, gnome-shell-3.36-3.38 carries version 37, and gnome-shell-3.32-3.34 carries version 33. Two older branches, gnome-shell-3.10-3.30 and gnome-shell-before-3.10, have no version number listed and cover GNOME 3.10 to 3.30 and GNOME 3.4 to 3.8 respectively.

This is the standard way GNOME Shell extensions handle a platform that changes its own API between releases, and the price is that a user on an older distribution has to switch branches before building or installing. Nothing in the README describes automatic detection of your Shell version, so the check is manual.

The version numbering also tells you something about maintenance history. Version 61 on master against version 33 on the oldest listed branch implies many releases in between, each presumably tracking a Shell release.

The default branch is master, and the repository has no GitHub releases, so there is no tag to fetch a zip from. Installation is either from the GNOME Extensions site or built locally.

The status indicator cup and its hidden requirement

The panel indicator is the part of Caffeine that people notice. It is a cup that is filled when the extension is enabled and empty when it is disabled, and it can be scrolled to change state directly.

Scrolling up on the indicator enables Caffeine, which gives a filled cup, and scrolling down disables it, which gives an empty cup. That is a faster interaction than opening the quick settings menu, and it works because the indicator sits in the top panel at all times.

The requirement is easy to miss. The README states that the option 'Show status indicator' must be set to 'always' for the scroll behaviour to work, and it is called out as a note directly under the scroll instructions. If the indicator is set to hide automatically, the scroll gesture has no target, and the quick settings toggle remains the only route.

The same panel area is where the timer option and the preferences live, so the extension's whole surface is reachable without opening a settings window: toggle, scroll, timer, preferences. The README also shows notification screenshots for both the enabled and disabled states, so the feedback loop is explicit rather than inferred.

Notifications matter more than they might seem. Without them, a user who enables Caffeine to watch a long video might not notice that it stayed on afterwards, and the machine would never suspend.

Timer mode bounds how long the session stays awake

The timer option enables Caffeine for a given amount of time, and the README compares the idea to Caffeine in LineageOS, which is the same name for a different platform's power control.

The behaviour is the obvious one: you pick a duration, the extension holds the session awake for that long and then releases it, so the machine returns to its normal suspend behaviour without you having to remember to switch it back. This is the option that makes the extension usable as a daily habit rather than a manual toggle, because a forgotten toggle is exactly the failure that leaves a laptop awake in a bag.

The README documents the option with screenshots of the timer off and on states and does not specify the range of durations the preferences offer, so treat the granularity as unknown until you open the preferences dialog. The same applies to whether the timer can be extended while it is running.

The build system gives a hint about the scope of the code without documenting behaviour. The Makefile passes an extra source file named mprisMediaPlayer2.js into the packaged extension, which indicates the extension includes MPRIS media player handling in its sources. The README does not describe any media player behaviour, so it would be wrong to claim the extension reacts to playback state based on the file name alone.

Building and installing with the bundled Makefile

Installing from source is two make targets. The README gives them directly:

make build
make install

After that you restart the shell and enable the extension from the extensions list.

The Makefile shows what those targets do. The build target removes any previous bundle, then runs gnome-extensions pack with the force flag, a locale directory, and the preferences and icons directories added as extra sources, before moving the resulting shell-extension zip to a file named [email protected] in the project root. The install target then runs gnome-extensions install on that bundle with the force flag. A default target runs build followed by install, so a bare make does both.

The extension directory itself is named [email protected], which is the UUID that GNOME uses to identify it, and the same string appears in the command line interface documented later. The Makefile also offers clean, translations, lint and lint-fix targets. Linting runs eslint over the extension directory, and the package manifest lists eslint and the stylistic plugin as dependencies, with an eslint.config.js at the repository root.

There is a Nix flake in the tree as well, with flake.nix and flake.lock, which is a convenient way to get a reproducible development environment for the linting and build steps.

The cli-toggle key drives it from a terminal

Caffeine can be queried and controlled without touching the shell at all, through a gsettings key exposed by the extension. The README documents the schema path under the extension's local schemas directory and the key org.gnome.shell.extensions.caffeine cli-toggle.

To read the current state:

gsettings --schemadir ~/.local/share/gnome-shell/extensions/[email protected]/schemas/ get org.gnome.shell.extensions.caffeine cli-toggle

To switch it on:

gsettings --schemadir ~/.local/share/gnome-shell/extensions/[email protected]/schemas/ set org.gnome.shell.extensions.caffeine cli-toggle true

The schemadir argument is what makes this work from a plain session: the compiled schema for the extension lives in the user extension directory rather than in a system path, so gsettings needs to be told where to look.

This is the hook for scripting. A keybinding can toggle Caffeine, a shell alias can wrap the set command, or a presentation script can disable suspend automatically and restore it afterwards. The README does not document a way to schedule the toggle or to set a duration from the command line, so scripted use is limited to the on and off states unless you drive the timer through the shell interface.

Caffeine against the GNOME session idle settings

The plain alternative is to change the session's own idle settings rather than install anything. GNOME exposes the screen blank delay and the session idle delay as desktop settings, so a user who always wants the machine awake can simply raise or disable those values in the power settings, and a user who never wants it can leave them alone.

The difference in approach is scope and reversibility. The session settings apply to every login session and persist across reboots, which makes them the wrong tool for a one-off need: you would be changing your laptop's behaviour for the rest of the day to cover five minutes of a video call. Caffeine is a session-scoped override that you can see in the panel and switch back with a scroll gesture.

The second difference is discoverability. A user who does not know the extension exists never changes anything; a user who has it in the quick settings menu reaches for it in one click. For a shared or work machine, where the person at the keyboard may not be the person who configured the power settings, that visibility is the point.

There is a limitation to accept either way. The README documents auto suspend control, and the repository description also mentions the screensaver, but the settings and screenshots it lists do not enumerate every element of screen blanking that the extension suppresses. If your workflow depends on the screen staying on for a specific reason, check what the extension actually holds back on your setup rather than assuming it covers all blanking paths.

A small GPL-2.0 extension with no release tags

Caffeine is distributed under the GNU General Public License version 2, with the text in the COPYING file at the repository root, and the README carries a licence badge pointing at that file. GPL-2.0 is a copyleft licence, so a modified version distributed to others carries the same licence obligation, which matters for anyone planning to fork it rather than merely install it.

The repository is not archived and the last push was on 2026-10-08, so the tree is still being worked on. What it does not have is a GitHub release, so there is no published zip and no versioned changelog to consult from the releases page, even though the README links to a latest release URL. Builds and installs therefore come from a branch or from the GNOME Extensions site, and the version numbers in the compatibility table are the closest thing to a changelog.

The code footprint is modest, which suits a utility of this kind. The top level holds the extension directory itself, the Makefile, the ESLint configuration, the Nix flake, an update-locale.sh script for translations, the resources and screenshots directories, and the README. The only npm dependencies are development tooling for linting; there is no runtime dependency to install.

For an upgrade, the practical sequence is to pull the branch that matches your Shell version and rebuild. Because the branches are pinned to Shell ranges, staying on master after a distribution upgrade is the step that tends to be forgotten.

Editorial conclusion

Adopt Caffeine if you want a per-session override of GNOME auto suspend without editing the session idle settings, and if your Shell version is covered by the master branch. Do not expect it to manage screen blanking beyond what the README documents, and check the version table before installing on an older Shell, because those releases live on separate branches. Verify first that the branch you need lists your GNOME version, then install the extension with make build and make install and confirm the cup icon appears in quick settings. The last push was on 2026-10-08.

Frequently asked questions

Official sources

1. eonpatapon/gnome-shell-extension-caffeine on GitHub
2. Issues
3. License: GPL-2.0
4. README