Caffeinate is a prefix-only launcher provider for Noctalia v4. Tell it how long to pause idle-triggered display, lock, and suspend actions; it restores normal idle behavior when the time expires.
It accepts the duration you actually want instead of limiting you to a fixed set of buttons:
>c 1h 30m
>c :45
>c ::30
>c 1,5h
Important
AI-assisted development disclosure: this plugin was designed and implemented with substantial help from an OpenAI Codex agent, under human direction and review. That fact is disclosed so people who avoid AI-assisted software can make an informed choice. Contributions remain the responsibility of the humans who submit and review them.
Type any supported duration and review the resolved action before starting the session.
The bar stays compact until you need it: hover for exact seconds, then left-click for presets, cancellation, and launcher access.
- Arbitrary finite durations from one second through 52 weeks.
- Friendly named units: seconds, minutes, hours, days, and weeks.
- Clock forms including
1:30,:30,1:30:15, and::30. - Flexible spacing and separators such as
1h30m,1h + 30m, and1 hour and 30 minutes. - Dot or comma decimal marks, followed by half-up rounding to whole seconds.
- Indefinite sessions using
on,forever,indefinite, or∞. - Live status and early cancellation from the launcher.
- A configurable launcher alias, defaulting to
c. - Editable and reorderable blank-query presets.
- An optional bar widget with a live session menu and hover countdown.
- Shared state with Noctalia's built-in Keep Awake control.
- Launcher icons that follow Noctalia's Tabler or native icon setting.
- Noctalia Shell 4.7.7 or newer in the v4 series.
- A compositor/session supported by Noctalia's idle inhibitor. Caffeinate is not Niri-specific.
Noctalia v5 uses a different plugin API and is not supported by this release.
The repository is a Noctalia custom plugin source:
- Open Noctalia Settings → Plugins → Sources.
- Add a source named
Caffeinate. - Use
https://github.com/josteinhanssen/caffeinate-provideras its URL. - Refresh the plugin list, install Caffeinate, and enable it.
- Open the launcher and type
>c, or use the canonical>caffeinate.
To show the session in your bar, add the Caffeinate widget through Noctalia's normal bar configuration. By default, its dimmed off-state remains available between sessions; this can be changed in the plugin settings.
For local development, copy or symlink the caffeinate/ directory into
Noctalia's plugin directory, then rescan or restart Noctalia:
ln -s "$PWD/caffeinate" \
"${XDG_CONFIG_HOME:-$HOME/.config}/noctalia/plugins/caffeinate"Noctalia may use a source-hash prefix for plugins installed from custom repositories; installing through the UI is the supported end-user path.
| Launcher input | Result |
|---|---|
>c 30m |
Caffeinate for 30 minutes |
>c 1h 30m |
Caffeinate for 1 hour 30 minutes |
>c 1:30 |
Caffeinate for 1 hour 30 minutes |
>c :30 |
Caffeinate for 30 minutes |
>c ::30 |
Caffeinate for 30 seconds |
>c 1,5h |
Caffeinate for 1 hour 30 minutes |
>c forever |
Caffeinate until explicitly stopped |
>c status |
Show the live current status |
>c off |
End the current session |
stop and cancel are synonyms for off; on, indefinite, and ∞ are
synonyms for forever.
Clock-form minute and second fields must stay below 60, so 1:90 is rejected.
Named components are additive, so 1h90m resolves to 2h 30m.
Named-unit components may be concatenated or separated by whitespace, a comma,
+, -, or and. Separators may be mixed:
>c 1week, 2days + 3hours and 4minutes
A comma between digits is treated as a decimal mark (1,5h); a comma after a
unit is treated as a separator (1h, 30m).
There is one shared Noctalia Keep Awake session. Starting a new duration replaces the current remaining time; it does not extend or stack it. Ending a session from Caffeinate also ends a session started with Noctalia's built-in Keep Awake control, and vice versa.
During a finite session, the bar widget always shows a compact rounded-to-minute countdown. After Noctalia's normal hover delay, it expands to show the exact remaining time, including seconds:
- Left-click opens a session menu for cancelling the current session, opening the launcher, or starting/replacing a session with a configured preset.
- Right-click opens a context menu with Widget settings.
When no session is current, the widget uses a dimmed coffee-off icon. Enable
Hide when inactive if you prefer it to take no bar space between sessions.
Caffeinate inhibits idle-triggered actions. It does not override:
- explicit suspend, shutdown, lock, or display-off actions;
- laptop-lid behavior;
- critical-battery handling;
- administrative or system power policy.
Sessions belong to the current Noctalia runtime. Restarting or terminating Noctalia ends the session; sessions are not restored.
Open Noctalia Settings → Plugins → Caffeinate to:
- change or disable the
calias; - add, remove, and reorder finite presets;
- show or hide the Until stopped preset;
- hide the bar widget when no session is current;
- reset all plugin settings to their defaults.
The canonical >caffeinate prefix is always available. Prefix collisions are
resolved by Noctalia using provider registration order, so choose another
alias if >c is already claimed in your setup.
The parser and launcher behavior are tested without activating the desktop inhibitor:
./scripts/checkSee CONTRIBUTE.md for prerequisites, project structure, branch strategy, testing, and pull-request expectations. The detailed behavior contract lives in docs/specification.md, and the research behind the project is in docs/research/existing-caffeinate-options.md.
- Contributions: CONTRIBUTE.md
- Support: SUPPORT.md
- Security reports: SECURITY.md
- Community conduct: CODE_OF_CONDUCT.md
Caffeinate is available under the MIT License.