Hyper Window Toolkit

Window titles, grouped window actions, and workspace-aware behavior for Hyper.

Previously named hyper-active-tab-window-title. This repository preserves that plugin's history and adds an optional desktop companion for Cinnamon/X11.

Features

• Show the active tab's title in the native window title, taskbar and Alt+Tab.
• Update titles when the active tab, terminal title or focused pane changes.
• Preserve launcher profile titles until explicitly unlocked.
• Minimize and restore Hyper windows together within the active workspace.
• Bring the local group forward while keeping the selected window on top.
• Leave windows in other workspaces untouched; group actions do not switch workspaces.
• Keep windows independent when closing them: closing one never closes the group.

For example, with one Hyper window in WS1 and two in WS2, restoring Hyper in WS1 only restores its one window. In WS2, restoring either window restores that workspace's pair. Minimization follows the same rule. Pinned windows participate in the active workspace's group.

Compatibility

The title plugin was tested with Hyper 3.4.1. The grouped-window companion was tested on Linux Mint with Cinnamon/X11, Python 3, libwnck and a systemd user session. Workspace grouping on Wayland, macOS and Windows is not implemented.

The companion uses the window manager's workspace membership, including minimized windows. Background events are ignored, delayed presentation requests are discarded after a workspace change, and pending actions in another workspace do not block the current group.

Install

1. Title plugin

git clone https://github.com/LuchoNoPrograma/hyper-window-toolkit.git \
  ~/.hyper_plugins/local/hyper-window-toolkit

Add hyper-window-toolkit to the existing localPlugins array in ~/.hyper.js, preserving your other plugins:

localPlugins: ['hyper-window-toolkit']

Restart Hyper when convenient to load the plugin. Installation from source is supported; this project is not claiming an npm release under the new name.

2. Workspace grouping (Cinnamon/X11)

On Linux Mint / Ubuntu, install the runtime dependencies:

sudo apt install python3-gi python3-xlib gir1.2-wnck-3.0 gir1.2-gtk-3.0

Run the companion installer from your graphical session:

cd ~/.hyper_plugins/local/hyper-window-toolkit
python3 linux/install.py

It installs and starts the hyper-window-sync.service user service, enables it for future sessions, and installs a Cinnamon autostart entry to import the graphical session environment. No administrator access is needed for the companion installation. Existing files are backed up under ~/.local/state/hyper-window-toolkit/backups/.

The service name stays hyper-window-sync.service to upgrade existing installations without running two synchronizers. A process lock also prevents duplicate instances. The installer does not edit Hyper's configuration.

Keep Cinnamon's grouped window list setting Show windows from all workspaces disabled so panel selection also stays local. The companion does not override an explicit selection of a window in another workspace.

Check the running service:

systemctl --user status hyper-window-sync.service
journalctl --user -u hyper-window-sync.service

Migrate an existing installation

Rename the old checkout, update its remote, and replace hyper-active-tab-window-title with hyper-window-toolkit in ~/.hyper.js:

mv ~/.hyper_plugins/local/hyper-active-tab-window-title \
  ~/.hyper_plugins/local/hyper-window-toolkit
cd ~/.hyper_plugins/local/hyper-window-toolkit
git remote set-url origin https://github.com/LuchoNoPrograma/hyper-window-toolkit.git

Preserve any local modifications before updating your checkout. After updating, run python3 linux/install.py to install the current companion. Do not enable both plugin names simultaneously.

Launcher title protocol

The plugin advertises NINI_AGENTS_HYPER_TITLE_LOCK=1 for compatibility with existing launchers. A terminal title beginning with __MULTICLI_TITLE_LOCK__: pins that terminal's profile title. The exact title __MULTICLI_TITLE_UNLOCK__ releases it and restores normal title updates. Each terminal tracks its own lock; an empty lock releases it. Without a custom title the window falls back to Hyper.

Development

Requires Node.js 18+ and Python 3. Unit tests use mocks and do not manipulate desktop windows or require graphical libraries:

npm test

Individual suites:

npm run test:titles
npm run test:windows

An optional live regression test requires the companion installed and exactly three existing, unpinned Hyper windows and at least two workspaces:

/usr/bin/python3 tests/check_workspaces_live.py

This live test temporarily moves, focuses and minimizes the existing windows. It restores their workspaces, minimized states and focus in a finally block and leaves the companion running. Run it only when desktop interaction can be interrupted; it does not close terminal sessions. It verifies the one-window / two-window workspace scenario in both directions.

To inspect installer output without starting services, set a temporary HOME and use python3 linux/install.py --no-start. That mode writes files but skips runtime checks and systemd commands.

Uninstall companion

systemctl --user disable --now hyper-window-sync.service
rm ~/.config/autostart/hyper-window-sync.desktop
rm ~/.config/systemd/user/hyper-window-sync.service
rm ~/.local/bin/hyper-window-sync ~/.local/bin/hyper-window-sync-start
systemctl --user daemon-reload

To remove title integration, remove hyper-window-toolkit from localPlugins and restart Hyper.

License

MIT