AGENTS.md

Guidance for AI coding agents working on this repository. See README.md for what the script does from a user's point of view.

Project overview

Steamify CachyOS: a bash wizard that makes CachyOS (KDE Plasma 6 + plasma-login-manager) boot into a SteamOS-style gamescope session, with working switching between gamescope and the Plasma desktop. Primary target: the Valve Steam Machine (DMI Valve/Fremont) running CachyOS Desktop edition.

Layout

steamify.sh - the only entry point. Pre-flight checks, sources lib/*.sh, runs the menu and applies the plan. No component logic here.
patches/ - kernel module sources and patches the scripts build or apply, never inline in the shell code. Read them with patch_file <name> (lib/common.sh, from the checkout); the bundle embeds every file in patches/ and overrides patch_file. Add new ones to its README.
services/ - the systemd units the scripts install (.service, .timer, .path), never inline in the shell code. Read them with service_file <name> [KEY=value...] (lib/common.sh), which fills in @KEY@ placeholders; the bundle embeds every file in services/ too (service_raw). Add new ones to its README. Small drop-ins for other packages' units stay inline.
ui/ - the app: steamify-ui (PySide6; runs steamify.sh --backend, lib/backend.sh) and ui/qml/: Main.qml (window, header, which screen shows), AppState.qml (all state and logic, input actions), one *Screen.qml per screen, small widgets (Btn, Chip, Badge, ...), and the singletons Theme (colours, fonts), Texts (item texts) and Input (controller/keyboard/remote and its button names), listed in qmldir. Screens get the AppState as app and only show it or call its functions.
Paths. Everything in the home folder lives under steamify: $STATE_DIR (~/.local/state/steamify), $STEAMIFY_DATA/$STEAMIFY_BIN (~/.local/share/steamify/{app,bin}), lib/state.sh. Never add files under the old name cachyos-gamescope-boot; migrate_layout moves those of older versions (symlinks keep older releases working). Keep the .bak-gamescope-wizard backup suffix: existing backups are found by it.
lib/*.sh - one file per responsibility, each defining functions only (no top-level side effects besides constants). See the table in TECHNICAL.md.
Components. Every menu item <id> (listed in COMPONENTS and LABEL in lib/menu.sh) provides <id>_status (return 0 if on, detected from the system, no state file needed), <id>_enable and <id>_disable, all idempotent. <id>_enable is also used to re-apply. Optional <id>_available is checked via component_available (e.g. machine only on Fremont). Turn-on order is COMPONENTS order, turn-off reverse; gaming must stay first. Dependencies live in toggle_component.
NVIDIA (lib/nvidia.sh): gamescope's session is broken on NVIDIA, so the SteamOS conversion (gaming, boot, single, glyphs) is hidden there (unless already on) and nvidia + its sub-option bigpicture ("Gaming on NVIDIA") replace it: Steam on the Plasma desktop, started at login. Never reintroduce a gamescope session for NVIDIA without re-testing on the hardware (notes: steamify-cachyos-dev, nvidia/). It can't be tested without the hardware: keep the branch behind .no-release-yet until it was.
Feature versions. Set FEATURE_VERSION[<id>] (lib/menu.sh) to the new VERSION whenever what <id>_enable sets up changes (a new component gets one too): installs recorded with an older version are ticked and re-applied ("update" in the plan and the app). New default options are ticked for installs whose parent (top-level: gaming) is on (feature_new, shown as "new"). New opt-in options (NO_PRESELECT) get the same "new" badge without being ticked (feature_new_optin). Both count "Gaming on NVIDIA" as a parent where the conversion isn't offered. Options shown but left unticked in a confirmed run are recorded as off (feature_record_unticked), or feature_new would tick them again. Status still comes from the system; don't add ad-hoc <id>_repair checks for new changes.
Reversibility. Every per-user KDE setting a component changes goes through kset <component> <file> <group|group> <key> <value> (lib/state.sh), which records the old value once; <id>_disable calls krevert <component>. Never call kwriteconfig6 directly for settings a component owns. System files are backed up with backup_file and restored on disable.
Single-file build. .github/tools/bundle.sh inlines lib/*.sh in the order of the entry point's for lib in ...; do source loop and wraps everything after that loop in main(). Keep that loop on one line, keep all logic in functions, and don't rely on SCRIPT_DIR for anything but sourcing. The workflow is one file for GitHub and a Gitea mirror (github.server_url): build and check run on both (shellcheck through ludeeus/action-shellcheck, which brings its own binary; the artifact with upload-artifact@v4 on GitHub and christopherhx/gitea-upload-artifact@v4 elsewhere: never mention upload-artifact@v3, GitHub fails a workflow for a deprecated version even in a skipped step); the release is gh on GitHub and akkuman/gitea-release-action on Gitea. A new release on GitHub also starts the Steamify ISO's release (gh workflow run iso-1-github-tag.yml in steamify-cachyos-live-iso, secret ISO_DISPATCH_TOKEN; skipped without it): the ISO repo's GitHub tag names it, the Gitea mirror builds it. CI (.github/workflows/bundle.yml) publishes the bundle as release v$VERSION on pushes to main; an existing version is never overwritten, so bump VERSION for every release.

Conventions

Bash, set -uo pipefail (no -e): check exit codes of steps that matter explicitly (|| { err ...; exit 1; } or || return 1).
Use the helpers from lib/common.sh (info, ok, warn, err, ask_yn, backup_file) for all output and prompts.
Runs as the normal user; use sudo per command, never require root. Per-user files go in $HOME of the invoking user (the script refuses to configure another user).
Idempotent: every step must be safe to re-run without duplicating lines or settings. Back up system files with backup_file before the first edit.
Don't overwrite package-owned files in /etc/xdg or /usr. KDE settings go into the user's config via kwriteconfig6 (or merge_kde_config for whole Valve ini files).
Package installs after a user already confirmed use --noconfirm: a second pacman prompt consumes the next scripted answer.
Comments explain why (the CachyOS/Plasma quirk being worked around), not what the next line does.
Versioning and releases. SemVer in VERSION (steamify.sh, shown in the menu header and the bundle header).
- Every commit gets an entry in CHANGELOG.md under its version (short hash
  - subject; a commit can't contain its own hash, so fill it in with the next commit). The section heading must be ## <VERSION> - <date>: CI cuts the release notes out of the changelog by that heading.
- Branches: one release branch per version. Work for a release goes into release/X.Y.Z (e.g. release/2.7.0), branched from main when that version starts. That branch bumps VERSION to X.Y.Z and adds the ## X.Y.Z - <date> changelog section (first commit on it).
  - Every change gets its own branch from the release branch: feature/<name> (new behaviour) or bugfix/<name> (a fix), and a pull request into the release branch, not into main. Its commits add their changelog lines to that version's section.
  - When the release is done and tested (the test plan in steamify-cachyos-dev, TESTPLAN.md), the release branch gets a pull request into main. Merging it publishes the release (below).
  - A fix for a released version: a new release/X.Y.Z+1 from main, with the bugfix/ branch into it; don't reopen an old release branch.
  - Up to the release branch, the agent manages it: create the feature//bugfix/ branches, commit, push, and merge them into the release branch itself once tested (with gh: gh pr create --base release/X.Y.Z + gh pr merge --merge; no review needed). Without gh (command -v gh), ask the user to install it (Ubuntu: sudo apt install gh, then gh auth login) instead of working around it. Only the release branch's pull request into main is the user's: never commit or merge to main, the user merges that one. Never work directly on main or a release/* branch either: edits, even uncommitted ones, go on a feature//bugfix/ branch (create it before editing; the release branch only gets the version-bump commit and merged PRs). Don't push a new release/* branch before it's needed: a push can start CI builds (a dev ISO). A machine without a git identity: pass the repo's author per command (git -c user.name=... -c user.email=... commit, taken from git log) instead of changing the git config. A .no-release-yet file at the root of a feature/bugfix branch means it must not be merged into the release branch yet (work in progress, untested on hardware). When the feature is complete, ask the user whether it may be released; on a yes, delete the file, then open the pull request and merge it. Keep a feature/bugfix branch up to date by merging (or rebasing on) its release branch, the release branch by merging main when that moved.
- A push to main publishes release v$VERSION (tag + bundle + that changelog section) and marks it latest. An existing version is never overwritten: without a bump nothing is released, and pull requests show a warning when VERSION is a version that's already released (so a release branch that forgot its bump shows it on every PR).
- A release that adds, removes or renames a menu row also retakes the README screenshots (assets/screenshot-menu-steam-machine.png and assets/screenshot-menu-nvidia.png, side by side in the README): the app from the branch on a Steam Machine and on a PC with an NVIDIA card, every row visible and each window only as tall as its options need, the header showing the new VERSION, 1600 px wide. Size the window with a KWin script (match the steamify-ui class exactly: a title match also hits Konsole and editor windows) and crop the full-screen capture to the client rectangle; mind the display scale (the Steam Machine runs at 1.75).
- Users install through releases/latest/download/steamify.sh (GitHub's newest release). The latest tag and release follow the newest version tag too (moved, asset replaced, when a new version is released), so the older URL releases/download/latest/... keeps working.

Non-obvious behaviour to preserve

apply_changes sets $LOGIN_MANAGER from the menu: sddm when single user mode is wanted, else plasmalogin. Toggling single user re-applies gaming so it moves to the other login manager. Single user mode hides the launcher's Session dropdown via kickoff primaryActions=3 (restricting action/logout also hides Restart/Shut Down). Two login-manager paths: sddm (like SteamOS: steam-set-session writes /etc/sddm.conf.d/zz-steamos-autologin.conf, which SDDM honours; we add User=/Relogin= in 10-gamescope-autologin.conf, and /etc/sddm.conf must not contain [Autologin] since it's read last) and plasmalogin (needs the sync bridge and the shortcut's sudoers rule). Both must keep working.
steam-set-session only writes /etc/plasmalogin.conf.d/zz-steamos-autologin.conf; the base /etc/plasmalogin.conf wins, hence the sync bridge. The sync service needs StartLimitIntervalSec=0, or bursts of session switches get it rate-limited and all later switches silently stop working.
The sync script must only edit Session= inside [Autologin].
The Steam desktop autostart unit is guarded with ExecCondition=... XDG_CURRENT_DESKTOP = KDE, so it doesn't start a second Steam inside gamescope.
Vapor theme: comes from the cachyos-vapor package (system-wide, in /usr/share); only remove it on disable if we installed it. It is applied with lookandfeeltool --resetLayout ("Desktop and window layout"), which replaces the panel/desktop layout: the layout files are backed up to $STATE_DIR/theme-layout and restored, and every key from Vapor's contents/defaults goes through kset first. plasma-apply-colorscheme runs with the ColorScheme key cleared, since it skips a scheme already named there. The layout reset drops single user's launcher settings, so single_launcher is re-applied.
SteamOS extras (lib/steamos-extras.sh, part of the theme): downloaded from Valve's newest steamdeck-kde-presets (repo db gives name + SHA-256) into /usr/local, never /usr. gaming-return.svg is a symlink in the package: install steam-gaming-return.svg under that name. The shortcut's icon is switched with set_shortcut_icon, since the conversion is created before the theme. An existing KWallet is never replaced or removed.
Plasma 6 has no separate systemtray containment: tray settings live on the systemtray applet itself (Valve's setup script targets Plasma 5).
Restart plasmashell via systemctl --user (plasma-plasmashell.service), not plasmashell --replace from the script's shell: a shell without the session environment yields a light-themed desktop (context menus, apps it launches).
Live Plasma changes (qdbus6 ... evaluateScript, lookandfeeltool) only run when plasmashell is running; config-file fallbacks cover the rest.
plasmashell writes its in-memory config back on exit: edit panel/applet/ wallpaper files only between stop_plasmashell_for_edit and restart_plasmashell_if_stopped (lib/common.sh).
LED driver: leds-valve-dkms-git's Makefile builds against uname -r, not DKMS's target kernel: /etc/dkms/leds-valve-dkms.conf sets MAKE[0]="make KVERSION=${kernelver}" (written before the AUR install; someone's own override there is backed up, kept with ours appended, and restored on disable). Without it, other kernels build against the running kernel's tree and fail (CachyOS kernels are clang-built; DKMS adds LLVM=1 only for the target's tree). Headers for every installed kernel are installed first, and ensure-kernel-headers.service installs missing ones at boot (a pacman hook can't run pacman), which triggers DKMS's install hook. The module creates /sys/class/leds/valve-leds*.
boot ("Boot into: [gamescope] / desktop") is a choice row, not a checkbox: on = desktop. It's a sub-option of the conversion: menu_visible only shows it (indented, └) while gaming is ticked, so menu numbers after it shift by one when the conversion is unticked. It needs gaming (ticking it ticks gaming, unticking gaming unticks it) and is never preselected (NO_PRESELECT), so the conversion boots into gamescope by default. Desktop is steamify-boot-desktop.service, ordered Before= the login managers: steam-set-session plasma.desktop plus the plasmalogin sync bridge when it exists, at every boot. CachyOS's cachyos-gamescope-autologin still sets gamescope during each desktop session; the unit corrects it at boot.
bios is an action (ACTIONS in lib/menu.sh) and a sub-option of machine, not an on/off component: never preselected (not even on a first run), never re-applied by a, not listed in the state overview, and bios_status is always off. Only selectable when Valve's version differs from the installed one (component_selectable, greyed out otherwise). Download, SHA-256 and the fwupd device check (get-details --json: no UpdateError) come before the warnings. The warning box uses █ for its frame: Konsole draws a long coloured row of # narrower, so the right edge wouldn't line up. Keep both confirmations (y/N, then typing UPDATE) and the warnings; the firmware comes from the newest holo-X.Y repo (.files db names the .cab, .db gives the SHA-256), and fwupd itself refuses non-Fremont hardware. In the VM, test it with WIZARD_BIOS_DRY_RUN=1 (skips only the device check, never flashes) and a faked version (dev-env BIOS_VERSION=F7F0107 ./run.sh --fremont).
The entry point loops: menu, run, "back to the menu" (or [m]/[r] when a restart is needed), until q. When a restart is needed, q asks "Restart now? [Y/n]" (quit_prompt): n goes back to the menu, the next q asks again. Scripted input that runs out quits without restarting (never restart on EOF: ask_yn would take its default).
Steamify shortcut (launcher): "Steamify CachyOS" (desktop and launcher, id steamify-ui.desktop, the app's own id) runs curl | bash of releases/latest/download/steamify-app.sh without a terminal (in Konsole only while PySide6 is missing, for sudo); "Steamify Terminal" (launcher) runs steamify.sh in Konsole. Both always the newest release. The entry has X-Steamify-Shortcut=true: steamify-app.sh doesn't overwrite it, and disable only removes it then. A pre-2.0.1 shortcut (terminal only) is ticked by launcher_repair. Its icon, assets/steam-gaming-settings.svg (Valve's GPL-2.0 return icon with a gear), is a release asset too, and is downloaded from there (Steam's icon if that fails). Desktop files are written with their mode already set (install_executable): Plasma opens a desktop icon it first saw non-executable in an editor. The start script closes its window after a 10-second countdown on success and waits for Enter after an error; it uses pipefail, or a failed download would run an empty script and count as success.
HDMI refresh boost (hdmi, lib/hdmi-refresh.sh): retired in 2.2.0 (it needed the pinned kernel); only removal is left (see the power-off fix below). hdmi_enable refuses. debugfs is root-only (glob it under sudo), and edid_override takes exactly reset with no newline.
Steam Machine CEC driver (cec_driver_enable, lib/cec.sh): mainline cros_ec_cec lacks Fremont, so HDMI-CEC builds Valve's copy (evlaV linux-integration, pinned commit + SHA-256) with DKMS for every kernel. It's patched to register its notifier without a port name when the board has one CEC port: amdgpu registers its HDMI notifier nameless, and the kernel only pairs that with a named lookup ("Port C") when the CEC driver registered first, which never happens since amdgpu loads from the initramfs. Without it /dev/cec0 exists but stays at f.f.f.f. The source comes from one raw.githubusercontent.com download, which GitHub rate-limits (HTTP 429 after a day of test installs, per address): it's kept in /var/cache/steamify/cros-ec-cec-<sha256:12>.c and reused while its checksum matches. The name carries the checksum, so a new pin (commit + SHA-256 in lib/cec.sh) downloads its own file once and removes the old one. The repo is an unofficial mirror of Valve's kernel without releases: if it ever disappears, ship the file with Steamify. The test VMs share the host's cache.
Power-off fix (poweroff, lib/fremont-poweroff.sh, a default sub-option of machine): recent kernels (7.2 and the 6.x/7.0/7.1 updates with the backport) keep the firmware's S4/S5 wake bit on GPIO pin 18, so the Steam Machine boots again right after powering off (Valve's kernel clears it at probe, not for upstream). The DKMS module steamify-fremont-poweroff (patches/steamify-fremont-poweroff.c) clears it in a power-off-prepare handler, built for each kernel. It made the kernel pin unnecessary: kpin is only available while on (kpin_available), and detect_components unticks it, so a normal run removes an existing pin. hdmi (it needed the pin) is retired the same way: hdmi_status is on while anything of it is left (saved displays, hotplug unit, EDID files, old kernel parameter), hdmi_available only then, it's always unticked, and hdmi_disable removes all of it. CachyOS's linux-cachyos is clang-built, -bore GCC-built: let DKMS pick the compiler, never pass LLVM=1. Test shutdown on the real machine for every new major kernel.
Add as non-Steam game (steamgame, lib/steam-game.sh, sub-option of launcher, ticked along with it, 2.5.1): edits Steam's shortcuts.vdf with patches/steam-shortcuts.py only while Steam is closed (Steam rewrites it on exit), then starts Steam again. Never close Steam in gaming mode or when SteamGameId is set (the run is a Steam game). An existing entry for the start script is updated, not doubled; removal takes every entry for it. Controller input through Steam's desktop layout arrives as keys: Enter must select (A), Esc must never quit (B); the app re-execs without Steam's overlay preload.
Update notifications (notify, lib/update-notifier.sh, top-level, ticked by default, 2.5.0): a user timer (daily, and the service is wanted by plasma-workspace.target) runs patches/steamify-notifier.py, which compares GitHub's newest release with the seen version every run records (notify_seen in the entry point, only while it's on, with frontend: app or terminal, which Open Steamify starts again, in a systemd-run --scope since the check's own unit is stopped when it exits). It must never update anything itself: notification + tray icon, Open Steamify / Skip this version (skipped). Desktop only (exits without plasmashell).
VRAM booster (vram, lib/vram-booster.sh, top-level, ticked by default, 2.3.0; only available when /sys/fs/cgroup/dmem.capacity lists a vram/vidmem region (numbered too) of at least 2 GB, whatever the brand; greyed out with an NVIDIA card whose driver lists none, vram_selectable, faked with WIZARD_VRAM_FAKE_NVIDIA=1; WIZARD_VRAM_CAPACITY=<file> reads the regions from a copy): CachyOS's dmemcg-booster (system + user service) and plasma-foreground-booster, like SteamOS 3.9's VRAM management. The latter only starts with kcgroupsrc [Foreground Booster] autostart=true (set with kset). Disable removes only the packages it installed (state_get vram installed_pkgs).
Install-time mode (steamify.sh --defaults, 2.6.0): applies what the menu would preselect, no menu or prompts (needs passwordless sudo). The Steam Machine ISO (steamify-cachyos-live-iso) runs it in the installer for a user who has never logged in: no session bus, user systemd or plasmashell. So every systemctl --user goes through user_systemctl (lib/common.sh; without a session only unit files change, via --root=/), and the theme, when the layout is still /etc/skel's, removes it so Plasma builds Vapor's layout at the first login. What needs that layout (single user's launcher) runs then, from a one-time autostart (lib/first-login.sh, --first-login) that also opens the app. --options <id>,... (exactly these on, the rest off; an item on brings its parent) and --boot gamescope|desktop (desktop only with gaming) (2.7.0, defaults_options in lib/menu.sh); the ISO's installer page passes them. Items this PC can't use are left off with a warning, not an error. steamify.sh --boot gamescope|desktop on its own (2.7.0, for scripts) only switches boot on an installed conversion: WANTED is CURRENT plus that, so no updates or removals a normal run would pick.
What Steam's System settings show (SteamOS conversion, 2.9.0): the OS name stays CachyOS's everywhere (legal clarity; Steam's OS Name is lsb_release -d, not touched). /etc/os-release gets VERSION_ID=steamos-X.Y (Steam's OS Version: Valve's newest jupiter repo; offline, the previous value), VERSION_CODENAME=steam-machine, VARIANT="Steamify <version>" and VARIANT_ID=steamify-<version> (Steam shows VARIANT_ID as OS Variant), refreshed by os_version_refresh after every run that changes something; a pacman hook (zz-steamify-os-release) runs after cachyos-hooks. KDE's About this System would show VERSION_ID after the name: kcm-about-distrorc UseOSReleaseVersion=true (kset) makes it show os-release's VERSION, which CachyOS doesn't have. Never NAME or PRETTY_NAME: limine-snapper-sync finds the boot entries by the OS name ("Target OS name ... not found in /boot/limine.conf"); /etc/default/limine gets TARGET_OS_NAME="CachyOS" when it has none, as a guard. The serial number (tmpfiles rule) is Steam Machine support's, so Fremont only.
Relogin=true means a gamescope that fails to start is relaunched in a tight loop; keep that in mind when changing session handling.

Checking changes

The bundle puts every module in one file, so shellcheck sees all their local variables together: don't reuse a name another module uses as an array (e.g. g in lib/state.sh), or CI's shellcheck on the bundle fails.

There is no test suite. At minimum:

for f in steamify.sh lib/*.sh; do bash -n "$f"; done
shellcheck -S warning steamify.sh lib/*.sh   # if available

Behaviour is verified in a CachyOS QEMU/KVM test VM. The VM scripts and a Claude Code skill describing the whole test workflow (snapshots, SSH, running the wizard with scripted menu input such as printf '2\n\ny\nn\n', the per-component checks; when stdin is not a terminal the menu falls back to a numbered prompt, which is what scripted runs use, reboot checks, the full test matrix, --fremont to fake Steam Machine hardware) live in steamify-cachyos-dev. Gamescope itself and the real LED bar can only be verified on hardware.

26 KiB Raw Blame History