Metadata-Version: 2.4
Name: sessionintent
Version: 0.4.3
Summary: A declarative session orchestration system for GNOME Wayland
License: MIT
Project-URL: Homepage, https://github.com/fazrigading/SessionIntent
Project-URL: Documentation, https://github.com/fazrigading/SessionIntent/docs
Project-URL: Source, https://github.com/fazrigading/SessionIntent
Project-URL: Issues, https://github.com/fazrigading/SessionIntent/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Dynamic: license-file

# SessionIntent: Declarative session orchestration for Linux desktops

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/sessionintent.svg)](https://pypi.org/project/sessionintent/)
[![CI](https://github.com/fazrigading/SessionIntent/actions/workflows/ci.yml/badge.svg)](https://github.com/fazrigading/SessionIntent/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/fazrigading/SessionIntent)](https://github.com/fazrigading/SessionIntent/releases)

SessionIntent switches between intent-based modes (work, gaming, browsing, …) that automatically launch, reuse, and organize applications across workspaces.

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

## 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

### Installation

#### Method 1: Using installer script (recommended)

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

#### Method 2: Using uv

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

Or run without installing:

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

#### Method 3: Manual installation (pip)
```bash
pip install .
```

Read [docs/INSTALLATION.md](docs/INSTALLATION.md) for details. Distro packages: PKGBUILD in `packaging/arch/`, Debian sources in `debian/`, Flatpak manifest in `packaging/flatpak/`, RPM spec in `packaging/fedora/` (all pending upload except the installer).

### Configuration

1. Initialize SessionIntent:
```bash
sessionintent init
```

2. Set up your apps:
```bash
sessionintent setup
```

3. Edit `~/.config/sessionintent/config.yaml` to define your modes, read [examples/config.example.yaml](examples/config.example.yaml) for reference.

4. Launch the mode selector:
```bash
sessionintent
```

Upgrading from flag-based CLI or `version: 1` configs? See [docs/MIGRATION.md](docs/MIGRATION.md).

## Usage

```bash
# 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) |

## Requirements

- Python 3.10+
- PyYAML
- wofi or rofi (OPTIONAL, for UI; terminal fallback otherwise)
- A supported desktop (GNOME, KDE, Hyprland, Sway, wlroots) or X11/EWMH

## License

GPL-3.0-or-later - see [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/ROADMAP.md](docs/ROADMAP.md) for details.

## Acknowledgments

- Provider-based multi-desktop support
- Inspired by window manager session management tools
