TUI session manager for NVIDIA Optimus laptops on Linux
envytui is a terminal-based session manager that runs at login and lets you switch between GPU and power profiles before your desktop starts. It wraps envycontrol and power-profiles-daemon behind a clean gum-powered interface.
- Three GPU profiles -- Battery (iGPU only), Performance (hybrid), and Max (dGPU only)
- Auto-detects your hardware -- GPU names, AC adapter, and current status shown in a dashboard
- Confirmation before reboot -- no accidental reboots
- Spinner feedback -- visual progress while settings are applied
- Works on any NVIDIA Optimus laptop -- Intel or AMD iGPU paired with an NVIDIA dGPU
- Distro-aware installer -- detects pacman, apt, dnf, and zypper
- Supports bash and zsh login hooks
- ShellCheck CI -- all scripts are linted on every push and PR
Any Linux laptop with an NVIDIA Optimus setup:
| iGPU | dGPU | Supported |
|---|---|---|
| AMD Radeon (Ryzen) | NVIDIA GeForce | Yes |
| Intel UHD/Iris | NVIDIA GeForce | Yes |
| AMD Radeon | AMD Radeon (discrete) | No |
| Intel | Intel Arc | No |
envytui delegates all GPU switching to envycontrol, which only supports NVIDIA Optimus configurations.
- gum -- TUI components
- envycontrol -- GPU mode switching
- powerprofilesctl (power-profiles-daemon) -- power profile management
lspci(pciutils) -- GPU detectionsudoaccess -- required for envycontrol and reboot
git clone https://github.com/karsterr/envytui.git
cd envytui
chmod +x install.sh
./install.shThe installer will:
- Check that all dependencies are installed (with distro-specific install hints)
- Copy scripts to
/usr/local/share/envytui - Create a symlink at
/usr/local/bin/envytui - Print login hook instructions for your shell
envytuiAdd the following to your shell's login profile (~/.zprofile for zsh, ~/.bash_profile for bash):
# --- envytui: session manager hook ---
if [[ $(tty) == /dev/tty1 && $- == *i* ]]; then
envytui
fi
# --- end envytui ---This ensures envytui only runs on TTY1 in interactive shells. SSH, SCP, and non-interactive sessions are unaffected.
| Profile | GPU Mode | Power Profile | AC Required |
|---|---|---|---|
| Battery | Integrated (iGPU only, dGPU off) | power-saver | No |
| Performance | Hybrid (iGPU + dGPU) | performance | Yes |
| Max | NVIDIA only (dGPU only) | performance | Yes |
| Skip | No changes | No changes | No |
- Dashboard -- On launch, envytui detects your GPUs, current mode, power profile, and AC status, and displays them in a status panel.
- Selection -- You pick a profile from the list (or skip).
- Authorization -- sudo is requested only when needed.
- Apply -- GPU mode is set via
envycontrol, power profile viapowerprofilesctl, with spinner feedback. - Confirm -- You're asked to confirm before rebooting.
- Reboot -- A 5-second countdown with Ctrl+C escape hatch. State is written so the next boot can confirm success.
- Validation -- On next login, envytui reads the state file, confirms the mode was applied, and clears the state.
envytui/
envytui.sh # Main dispatcher (phases: validate, dashboard, select, action, reboot)
lib/
gpu.sh # GPU detection (lspci) and envycontrol wrapper
power.sh # Power profile management and AC adapter detection
state.sh # State file read/write/clear
install.sh # Installer with dependency checks
.zprofile # Example login hook
.github/
workflows/
shellcheck.yml # CI: ShellCheck linting
ISSUE_TEMPLATE/
bug_report.md
feature_request.md
PULL_REQUEST_TEMPLATE.md
Nothing changes. envytui exits cleanly and your desktop session starts as normal.
envycontrol modifies Xorg/Wayland configuration files and kernel module blacklists that only take effect on the next boot. This is a limitation of how NVIDIA Optimus switching works on Linux, not an envytui design choice.
Yes. envycontrol supports both Xorg and Wayland. The GPU mode switching is compositor-agnostic.
Yes. Just run envytui manually from any TTY or terminal whenever you want to switch profiles. The login hook is optional.
envytui scans /sys/class/power_supply/*/type for entries with type Mains. If no AC adapter is found, a warning is printed to stderr and the AC power check is skipped (performance/max modes will still be available). If detection fails on your hardware, please open an issue with the output of ls /sys/class/power_supply/ and cat /sys/class/power_supply/*/type.
Not currently. envytui exposes the three modes that envycontrol supports (integrated, hybrid, nvidia) with sensible power profile pairings. If you need different combinations, you can modify the gpu_apply_profile and power_apply_profile functions in lib/gpu.sh and lib/power.sh.
No. envytui is designed for laptops with NVIDIA Optimus (dual-GPU) setups. Desktop PCs with a single GPU have no need for GPU mode switching.
This is expected when switching modes while in integrated mode. The NVIDIA GPU is powered off and invisible to the PCI bus. envycontrol still writes the configuration files, and the change will take effect after reboot. This is a warning, not an error.
Install envycontrol:
- Arch:
sudo pacman -S envycontrol - Other distros: See envycontrol installation docs
Check what your system names the AC adapter:
ls /sys/class/power_supply/
cat /sys/class/power_supply/*/typeIf no entry has type Mains, your kernel may not expose AC status through sysfs. Open an issue with this output.
- Check the state file:
cat ~/.config/envytui/state - Verify envycontrol applied the mode:
envycontrol --query - Check if the state was
PENDING(indicates reboot didn't complete) orREADY(indicates envytui didn't run on next boot -- check your login hook).
envytui needs sudo for envycontrol, powerprofilesctl, and reboot. Make sure your user is in the sudo / wheel group and can run sudo -v successfully.
Run ShellCheck locally before pushing:
shellcheck --severity=warning envytui.sh lib/*.sh install.shSee CONTRIBUTING.md for guidelines on reporting bugs, suggesting features, and submitting pull requests.
This project is licensed under the GNU General Public License v3.0. See LICENSE for details.