Stasis

A modern Wayland idle manager that knows when to step back.

Keep your session in perfect balance—automatically preventing idle when it matters, allowing it when it doesn't.

Warning

Stasis Has Just received a major update with some breaking changes. Please see wiki for details.

Join the Official Stasis Discord!
👉 Click here to join the community

Features • Installation • Quick Start • Compositor Support • Contributing

---

✨ Features

Stasis doesn't just lock your screen after a timer—it understands context. Watching a video? Reading a document? Playing music? Stasis detects these scenarios and intelligently manages idle behavior, so you never have to jiggle your mouse to prevent an unwanted screen lock.

• 🧠 Smart idle detection with configurable timeouts
• 🎵 Media-aware idle handling – automatically detects media playback
• 🚫 Application-specific inhibitors – prevent idle when specific apps are running
• ⏸️ Idle inhibitor respect – honors Wayland idle inhibitor protocols
• 🛌 Lid events via DBus – detect laptop lid open/close events to manage idle
• ⚙️ Flexible action system – supports named action blocks and custom commands
• 🔍 Regex pattern matching – powerful app filtering with regular expressions
• 📝 Clean configuration – uses the intuitive RUNE configuration language
• ⚡ Live reload – update configuration without restarting the daemon

🗺️ Roadmap

Stasis is evolving! Here’s what’s currently in progress, planned, and potential future features. Items are grouped to show what’s happening now and what’s coming next.

Complete

• Sequential action blocks – Action blocks run in the exact order defined in your config. Stasis maintains an internal index to track progress, making execution smarter and more reliable.
• Lock-centric design – When a lock-screen action block is present and properly configured, Stasis tracks the PID of the command it executes to ensure the sequence stays intact.
• Resume-command support – Each action block can run an optional follow-up command after completion.
• Event-driven, minimal polling – Stasis now relies primarily on two internal loops that notify others to wake from deep sleep, significantly reducing CPU and memory usage at idle.
• CLI per-state triggers – Trigger a specific state, the current state, or all states, all while respecting previously completed actions.

In Progress

• User profiles / presets – save and load different workflows for various scenarios (work, gaming, etc.).

Planned

• Custom notifications – display alerts for idle events or action execution.
• Logging & analytics – historical idle data for power/performance insights.
• Power-saving optimizations – CPU/GPU-aware idle handling.

📦 Installation

Arch Linux (AUR)

Install the stable release or latest development version:

# Stable release
yay -S stasis

# Or latest git version
yay -S stasis-git

Works with paru too:

paru -S stasis

NixOS

please note the note at the bottom about flakes and nix.

If you use Nix flakes, stasis provides a flake.nix so you can build or consume the package directly from flakes.

Quick ways to use stasis from flakes:

• Build directly from the remote flake (no local checkout required):

# build the stasis package from GitHub
nix build 'github:saltnpepper97/stasis#stasis'

• Add stasis as an input in your own flake.nix and reference the package in your outputs or NixOS configuration. Example (snippet):

inputs = {
  nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  stasis.url = "github:saltnpepper97/stasis";
};

outputs = { self, nixpkgs, ... }:
let
  system = "x86_64-linux"; # adjust for your host
in {
  # reference the stasis package from the stasis flake
  packages.${system}.my-stasis = self.inputs.stasis.packages.${system}.stasis;

  # Or add it to a NixOS configuration
  nixosConfigurations.<host> = nixpkgs.lib.nixosSystem {
    inherit system;
    modules = [ ./configuration.nix ];
    configuration = {
      environment.systemPackages = [ self.inputs.stasis.packages.${system}.stasis ];
    };
  };
}

Notes:

• please know this i am a complete noob in nix and flakes, so updates and fixes will be appreciated! --CamRed25

From Source

Build and install manually for maximum control:

# Clone and build
git clone https://github.com/saltnpepper97/stasis
cd stasis
cargo build --release --locked

# Install system-wide
sudo install -Dm755 target/release/stasis /usr/local/bin/stasis

# Or install to user directory
install -Dm755 target/release/stasis ~/.local/bin/stasis

🚀 Quick Start

1. Install Stasis using one of the methods above

2. Create your configuration at ~/.config/stasis/stasis.rune

3. Check the wiki for detailed configuration examples

4. Start the daemon and enjoy intelligent idle management!

For configuration examples, CLI options, and advanced usage, visit the full documentation.

Compositor Support

Stasis integrates with each compositor's native IPC protocol for optimal app detection and inhibition.

Compositor	Support Status	Notes
Niri	✅ Full Support	Tested and working perfectly
Hyprland	✅ Full Support	Native IPC integration
labwc	⚠️ Limited	Process-based fallback (details below)
River	⚠️ Limited	Process-based fallback (details below)
Your Favorite	🤝 PRs Welcome	Help us expand support!

📌 River & labwc Compatibility Notes

Both River and labwc have IPC protocol limitations that affect Stasis functionality:

• Limited window enumeration: These compositors don't provide complete window lists via IPC
• Fallback mode: Stasis uses process-based detection (sysinfo) for app inhibition
• Pattern adjustments: Executable names may differ from app IDs—check logs and adjust regex patterns accordingly

💡 Tip: When using River or labwc, include both exact executable names and flexible regex patterns in your inhibit_apps configuration. Enable verbose logging to see which apps are detected.

Want to Add Compositor Support?

We welcome contributions! Adding support typically involves:

1. Implementing the compositor's native IPC protocol
2. Adding window/app detection functionality
3. Testing with common applications

Check existing implementations in the codebase for reference, and don't hesitate to open an issue if you need guidance.

🔧 About RUNE Configuration

Stasis uses RUNE—a purpose-built configuration language that's both powerful and approachable.

Why RUNE?

• 📖 Human-readable: Clean syntax that makes sense at a glance
• 🔢 Variables: Define once, reference anywhere
• 🎯 Type-safe: Catch configuration errors before runtime
• 📦 Nested blocks: Organize complex configurations naturally
• 🔤 Raw strings: Use r"regex.*" for patterns without escaping hell
• 💬 Comments: Document your config with #
• 🏷️ Metadata: Add context with @ annotations

RUNE makes configuration feel less like programming and more like describing what you want—because that's what a config should be.

🤝 Contributing

Contributions make Stasis better for everyone! Here's how you can help:

Ways to Contribute

• 🐛 Report bugs – Open an issue with reproduction steps
• 💡 Suggest features – Share your use cases and ideas
• 🔧 Submit PRs – Fix bugs, add features, or improve code
• 📦 Package for distros – Make Stasis available to more users
• 📖 Improve docs – Better explanations, examples, and guides
• 🖥️ Add compositor support – Expand Wayland ecosystem compatibility

📄 License

Released under the MIT License – free to use, modify, and distribute.

---

_{Built with ❤️ for the Wayland community
Keeping your session in perfect balance between active and idle}