SessionIntent

Declarative session orchestration for Linux desktops
Describe your "intents" (modes) to orchestrate application launch, workspace layout, and session state.

SessionIntent is a declarative session orchestration system for Linux desktop environments, with a focus on GNOME and Wayland. It lets you define named session modes in YAML and automatically manage applications, workspaces, and desktop state as you switch between contexts such as browsing, work, media, or focus sessions.

Instead of launching apps manually each time, you define the behavior of a session once and let SessionIntent restore it consistently.

Features

• 🎯 Intent-based sessions - Define workflows as modes (work, browsing, gaming, …)
• 🖥️ Multi-desktop - Provider-based support for GNOME, KDE, Hyprland, Sway, wlroots, EWMH
• 🔋 Hardware awareness - Filter modes on battery vs AC power
• 📝 Declarative configuration - config.yaml modes + apps.yaml registry (version: 2 schema)
• 🔒 Safe by default - Reuse before launch; destructive actions are explicit commands
• 🎛️ Workspace orchestration - Per-workspace app placement with optional monitor; switches wait until the app window is visible (GNOME Shell 46–51 via bundled extension)
• 👁️ Mode preview - preview <mode> shows workspaces and apps before applying
• 🔔 Notifications - Desktop notice on every mode switch
• 🧩 Plugins - Drop-in hooks in ~/.config/sessionintent/plugins/
• 🧪 Dev mode - --dev prints commands instead of executing

Quick Start

Requirements

• Python 3.10+
• PyYAML
• wofi or rofi — optional, for the mode picker. Without either, SessionIntent falls back to a terminal menu.
• A supported DE or compositor: GNOME, KDE Plasma, Hyprland, Sway, wlroots, or X11/EWMH

Installation

Method 1: Installer script (recommended)

curl -fsSL https://raw.githubusercontent.com/fazrigading/SessionIntent/master/INSTALL.sh | bash

The script checks prerequisites, installs SessionIntent, seeds a default config, and sets up autostart.

Method 2: uv

uv tool install git+https://github.com/fazrigading/SessionIntent

To run without installing:

uvx --from git+https://github.com/fazrigading/SessionIntent sessionintent --help

Method 3: Distro packages

Fedora:

sudo dnf copr enable fazrigading/SessionIntent
sudo dnf install sessionintent -y

Note

The project name is case-sensitive. The RPM does not set up autostart, so run sessionintent init once after installing.

For Debian and Arch, there are no distro package yet. Install the dependencies, then use Method 1 or 2:

# Debian-based
sudo apt install python3-pip python3-yaml rofi
# Arch-based
sudo pacman -S python python-yaml rofi

Note

Only the Fedora RPM is built and published. packaging/arch/, debian/, and packaging/flatpak/ are kept as reference for downstream packagers.

Important

See docs/INSTALLATION.md for manual installs, uninstalling, custom install locations, and troubleshooting.

Configuration

1. Initialize SessionIntent. This writes a default config and installs the GNOME Shell workspace extension:

   sessionintent init

2. Choose the apps you want to manage:

   sessionintent setup

   Your selection is saved to ~/.config/sessionintent/apps.yaml.

3. Define your modes in ~/.config/sessionintent/config.yaml. See examples/config.example.yaml for reference.

4. Launch a mode:

   sessionintent                    # picker (needs wofi or rofi)
   sessionintent apply browsing     # apply directly, no picker

Warning

Upgrading from the flag-based CLI or version: 1 configs? See docs/MIGRATION.md.

Note

Backends are auto-detected: GNOME, KDE Plasma, Hyprland, Sway, generic wlroots, and an EWMH fallback. Override with --backend.

Usage

# Select mode via UI (requires wofi/rofi) - default behavior
sessionintent
sessionintent select

# Apply specific mode directly (without wofi/rofi)
sessionintent apply browsing

# Preview a mode without applying
sessionintent preview browsing

# Session control
sessionintent panic        # Clear state (no app termination)
sessionintent quit         # Gracefully close managed apps
sessionintent clear        # Clear state files only
sessionintent kill         # Force kill managed apps
sessionintent suspend      # Suspend session

# Status and listing
sessionintent status       # Show current status
sessionintent list         # List available modes

# Configuration
sessionintent init         # Initialize default configs and extension
sessionintent setup        # Set up SessionIntent (scan apps)
sessionintent scan         # Rescan installed apps
sessionintent scan --force # Rescan, ignore cache
sessionintent reload       # Reload configuration
sessionintent version      # Display version information

# Global flags (come before the command)
sessionintent --dev apply work
sessionintent --backend sway apply work
sessionintent --config ~/other.yaml list

Key Files

File	Purpose
~/.config/sessionintent/config.yaml	User mode definitions ($XDG_CONFIG_HOME honored)
~/.config/sessionintent/apps.yaml	User app registry
/usr/share/sessionintent/apps.yaml	System app registry
~/.local/state/sessionintent/current	Current session state ($XDG_STATE_HOME honored)

License

GPL-3.0-or-later - see LICENSE for details.

Contributing

Contributions are welcome! See CONTRIBUTING.md and docs/ROADMAP.md for details.

Acknowledgments

Inspired by window manager session management tools.

Author

Fazri Gading (Copyright 2026)