gosleep-timer

Rust TUI sleep timer for Linux desktop actions.

gosleep-timer waits for a configured duration, then runs post-countdown desktop commands such as switching workspace, stopping media, dimming brightness, muting audio, locking the session, killing selected processes, powering off/rebooting, or running custom shell commands.

Status

• Release tags: vMAJOR.MINOR.PATCH
• Primary repository: https://gitea.forust.xyz/forust/gosleep
• SSH upstream: ssh://git@gitssh.forust.xyz:2221/forust/gosleep.git

Features

• Single Rust binary, independent of Python.
• Ratatui/Crossterm terminal UI.
• YAML config at ~/.config/gosleep-timer/config.yaml or $XDG_CONFIG_HOME/gosleep-timer/config.yaml.
• CLI commands for init, status, validate, edit, preview, run, history, and stats.
• Time-left display and progress bar.
• Wrapped command preview for smaller terminals.
• Linux desktop action support for niri, Hyprland, KDE, playerctl, brightnessctl/light, PipeWire/PulseAudio, systemd, and custom shell commands.

Install

From source

git clone ssh://git@gitssh.forust.xyz:2221/forust/gosleep.git
cd gosleep
cargo build --release --locked
install -Dm755 target/release/gosleep-timer ~/.local/bin/gosleep-timer

From release artifact

Download gosleep-timer-<version>-linux-amd64 and its .sha256 from the Gitea release page, then:

sha256sum -c gosleep-timer-<version>-linux-amd64.sha256
install -Dm755 gosleep-timer-<version>-linux-amd64 ~/.local/bin/gosleep-timer

Usage

Open the TUI:

gosleep-timer

Initialize the default config:

gosleep-timer init

Preview commands that will run after the countdown:

gosleep-timer preview

Show the current config, enabled actions, and dangerous-action markers:

gosleep-timer status

Validate the config without starting the timer:

gosleep-timer validate

Open the config in $VISUAL, $EDITOR, or vi:

gosleep-timer edit

Run the saved timer config:

gosleep-timer run

Override the duration for one run:

gosleep-timer run 45m
gosleep-timer run 1h30m

Run the countdown without executing post-timer actions:

gosleep-timer run --dry-run 10s
gosleep-timer run --no-actions 10s

Inspect recorded sessions and aggregate stats:

gosleep-timer history
gosleep-timer stats

Use a custom config path:

gosleep-timer --config ./config.yaml preview

TUI Keys

Key	Action
j / Down	Move down
k / Up	Move up
Space / Enter	Toggle, cycle, or edit focused field
Enter while editing	Apply edit
Esc while editing	Cancel edit
r	Start/restart timer
p	Pause/resume running timer
x	Stop timer
s	Save config
q / Esc	Quit

Configuration

Default config:

duration: 25m
actions:
  workspace:
    enabled: true
    backend: auto
    number: 3
  media:
    enabled: true
    action: stop
  brightness:
    enabled: false
    value: 30
  mute:
    enabled: false
  lock:
    enabled: false
    command: loginctl lock-session
  kill:
    enabled: false
    processes: []
  power:
    mode: none
  custom:
    enabled: false
    commands: []

Supported values:

Field	Values
duration	Go-style duration strings such as 25m, 45m, 1h30m, 10s
actions.workspace.backend	auto, niri, hyprland, kde
actions.media.action	none, stop, pause, play-pause, next, previous
actions.power.mode	none, poweroff, reboot

Commands Run After Countdown

auto workspace backend tries:

niri msg action focus-workspace <number>
hyprctl dispatch workspace <number>
qdbus org.kde.KWin /KWin org.kde.KWin.setCurrentDesktop <number>

Other actions use common Linux desktop tools:

• playerctl
• brightnessctl or light
• wpctl or pactl
• loginctl
• pkill
• systemctl

Install only the tools needed for the actions you enable. Dangerous actions such as pkill, power actions, and common destructive custom commands are highlighted in red in the TUI preview.

History

Completed timer sessions are appended to history.yaml next to the active config file. If no poweroff or reboot action is configured, CLI run asks for wake confirmation after the timer finishes and records the elapsed sleep time.

Development

cargo fmt --check
cargo test --locked
cargo clippy --locked -- -D warnings
cargo build --release --locked

Local smoke test:

tmpdir="$(mktemp -d)"
cargo run -- --config "$tmpdir/config.yaml" init
cargo run -- --config "$tmpdir/config.yaml" preview

Versioning

Version is stored in:

• Cargo.toml
• Cargo.lock
• VERSION
• CHANGELOG.md

Release tags must match the package version:

git tag -a vMAJOR.MINOR.PATCH -m "gosleep-timer vMAJOR.MINOR.PATCH"
git push origin main
git push origin vMAJOR.MINOR.PATCH

Releases

Gitea Actions builds releases from tags matching v*.*.*.

Required runner tools:

• Rust stable toolchain with cargo, rustfmt, and clippy
• curl
• jq
• sha256sum

Release authentication:

• The workflow exposes Gitea Actions' built-in ${{ secrets.GITEA_TOKEN }} as GITEA_TOKEN.
• The workflow declares permissions: contents: write so the token can create releases and upload assets.

See RELEASING.md for the full release checklist.

License

MIT. See LICENSE.