From qol-plugin-alt-tab
Use when working on the qol-tray alt-tab plugin, including GPUI window list, X11 preview capture, config loading, and settings UI.
How this skill is triggered — by the user, by Claude, or both
Slash command
/qol-plugin-alt-tab:qol-plugin-alt-tabThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Better Alt+Tab experience for qol-tray (Linux and macOS). Shows a GPUI window list with live previews. Replaces the native OS Alt+Tab switcher by grabbing the key via qol-tray's hotkey system.
Better Alt+Tab experience for qol-tray (Linux and macOS). Shows a GPUI window list with live previews. Replaces the native OS Alt+Tab switcher by grabbing the key via qol-tray's hotkey system.
alt-tabopen -> ["--show"]open-reverse -> ["--show-reverse"]settings -> ["--settings"]/tmp/qol-alt-tab.sock. Command: alt-tab (no args → starts daemon).Alt Tab (Open/Next) (action run), Alt Tab (Previous) (action run, id open-reverse), separator, Settings (action settings).linux, macos#[cfg(test)]
mod tests {
use qol_tray::plugins::manifest::PluginManifest;
#[test]
fn validate_plugin_contract() {
let manifest_str =
std::fs::read_to_string("plugin.toml").expect("Failed to read plugin.toml");
let manifest: PluginManifest =
toml::from_str(&manifest_str).expect("Failed to parse plugin.toml");
manifest.validate().expect("Manifest validation failed");
}
}
Required Cargo.toml dev-dependencies:
[dev-dependencies]
qol-tray = { path = "../../qol-tray" }
toml = "0.9"
cargo build directly in dev mode.alt-tab binary in the plugin root — it will shadow target/debug/alt-tab.qol-tray resolves binaries in order: plugin root → target/debug/ → target/release/.cargo test to validate the contract before linking.| File / Dir | Purpose |
|---|---|
src/main.rs | Entry point: loads config, dispatches --show/--show-reverse/--kill to daemon or starts daemon via picker::run::run_app() |
src/daemon.rs | Unix socket daemon (show/kill/ping) via qol_plugin_api::daemon |
src/config.rs | TOML config loading via qol_config::load_plugin_config() |
src/picker/run.rs | Daemon event loop, cache management, dispatch_show() |
src/picker/mod.rs | Picker orchestration: open_picker() with cycle/reuse/create paths |
src/picker/create.rs | Window creation, pre_create_offscreen() for instant open |
src/picker/reuse.rs | Window reuse across opens (resize, reposition) |
src/picker/gather.rs | Window gathering from cache or live discovery |
src/app/mod.rs | AltTabApp GPUI component, focus + blur-out handling, centralized dismiss(), one-shot tap-too-fast Alt-release fallback |
src/app/render.rs | UI rendering: grid layout, transparency, card styling, on_modifiers_changed → dismiss when Alt drops in HoldToSwitch mode |
src/discovery/platform/macos/ | macOS window enumeration via CoreGraphics (z-order = MRU) |
src/discovery/platform/linux.rs | Linux window enumeration via x11rb _NET_CLIENT_LIST_STACKING |
src/capture/platform/macos.rs | macOS preview capture via CGWindowListCreateImage |
src/capture/platform/linux.rs | Linux preview capture via x11rb Composite GetImage |
src/actions/platform/ | Window actions (activate, close, quit, minimize) per platform |
ui/ | Settings HTML/JS/CSS served by qol-tray |
The plugin runs as a long-lived daemon because GPUI's GPU initialization is slow on cold start. The picker window is pre-created offscreen at boot for instant open.
Startup flow:
daemon.enabled = true)/tmp/qol-alt-tab.sock, initializes GPUI, pre-creates picker window offscreen--show invocation writes "show" to the socket (<5ms)Key invariants:
KeepAlive PopUp window via qol_plugin_api::keepalive prevents GPUI from quitting when picker is dismissedrefresh_cache_for_show) so MRU order is always currentwindow.set_background_appearance() + disable_window_shadow() on reuseConfig is loaded via qol_config::load_plugin_config(["plugin-alt-tab", "alt-tab"]) from qol-config.toml.
Key fields:
display.max_columns — max grid columnsdisplay.transparent_background — transparent window background (requires shadow disable on macOS)display.card_background_color / card_background_opacity — card stylingdisplay.show_minimized — include minimized windows in listdisplay.show_hotkey_hints — header bar with keybindingsdisplay.show_debug_overlay — debug headeraction_mode — hold_to_switch (release Alt to confirm) or sticky (press Enter)reset_selection_on_open — reset selection to index 0 each openopen_behavior — cycle_once or show_listlabel.* — label font size, show app name, show window titlePreview accuracy (Linux): X11 GetImage captures the off-screen buffer; minimised or occluded windows may return stale/blank pixels.
Wayland: Linux support uses x11rb only. Wayland support is not implemented.
ui/)The settings page is served by qol-tray at /plugins/plugin-alt-tab/. It reads and writes config via:
GET /api/plugins/plugin-alt-tab/config — load current configPUT /api/plugins/plugin-alt-tab/config — save updated config (body: JSON)The --settings runtime action opens this URL in the default browser.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub qol-tools/qol-skills --plugin qol-plugin-alt-tab