vyom

Vyom (व्योम) is Sanskrit for "sky": the space everything sits in.

Vyom replaces wofi in Vayu. Instead of scripts piping text rows into a generic list, each job is a tool: a small plugin with real layouts, live data, previews, toggles and a key for everything. Vyom is what they run in: one resident process with a shared panel, theme and plugin API, so every tool opens instantly and looks the same.

#The tools

Each tool is its own repository, so you install only the ones you want:

#Install

Requirements: Python 3.11+, PyGObject (with pycairo, for tools that draw), GTK 4, gtk4-layer-shell, a compositor with the layer-shell protocol (sway, Hyprland, river, Wayfire, labwc…), and a Nerd Font for the icons.

# Arch
sudo pacman -S --needed python-gobject python-cairo gtk4 gtk4-layer-shell ttf-jetbrains-mono-nerd

git clone https://github.com/Theyashsawarkar/vyom ~/.local/share/vyom/core
ln -s ~/.local/share/vyom/core/bin/vyom ~/.local/bin/vyom

# then the tools you want, e.g.
git clone https://github.com/Theyashsawarkar/dvara ~/.local/share/vyom/plugins/dvara
git clone https://github.com/Theyashsawarkar/ganit ~/.local/share/vyom/plugins/ganit

In your compositor (sway shown):

exec vyom daemon                      # start it in the background at login
bindsym $mod+d exec vyom dvara        # each tool on its own key; again closes it
bindsym $mod+c exec vyom ganit
layer_effects "vyom" {                # SwayFX: blurred glass behind every panel
    blur enable
    corner_radius 20
    shadows enable
}

#Usage

vyom <tool> [args]        open a tool (e.g. vyom tarang, vyom raga video); again closes it
vyom dmenu [-p PROMPT] [--markup] < lines
                          pick one line: printed on stdout, exit 1 on Esc (like wofi --dmenu)
vyom list                 installed tools, and why one is skipped
vyom daemon | reload | quit
vyom quick                quick settings (the kendra tool)

Vyom keeps one resident process (a GTK single-instance app). Once it's running, vyom <tool> only sends it a D-Bus message, so a panel opens in well under a tenth of a second. vyom dmenu makes any script's picker a Vyom panel: printf 'Accept\nReject\n' | vyom dmenu -p "Pair?".

Every panel: type to search, Up/Down (or Ctrl+K/Ctrl+J) move, Page Up/Page Down jump, Enter runs, Tab switches to the next tool, Esc closes. Each tool adds its own keys (shown in its footer and README).

#Configuration

~/.config/vyom/config.toml, all optional (examples/config.toml):

[vyom]
disabled = ["raga"]          # installed tools not to load
cycle = ["dvara", "ganit"]   # Tab order
width = 900                  # every panel opens at this size (times scale = 1.25)
height = 520
opacity = 0.72               # panel background: 1 solid, lower = more glass

[plugin.tarang]              # each tool's settings: see its README
hotspot_command = "vayu-hotspot"

~/.config/vyom/style.css loads last, to restyle anything.

#Writing a tool

A tool is a directory with a plugin.toml and a Python package of the same name exporting a Plugin class:

# plugin.toml
name = "hello"
title = "Hello"
version = "0.1.0"
vyom = "0.2"
icon = "󰞅"          # Nerd Font glyph for the mode pill
color = "mauve"     # sky blue teal red peach mauve yellow green rose lavender
requires = []       # tools it needs; it's skipped (with the reason) without them

# hello/__init__.py
from vyom import Hint, Plugin as Base, Row, Section, ui, util

class Plugin(Base):
    preview = True                       # a preview pane on the right
    hints = [Hint("Enter", "greet")]

    def search(self, query):             # runs in a worker thread
        return [Section("People"), Row("World", "the usual", icon="󰞅", data="world")]

    def build_preview(self, row):        # main thread
        return ui.vbox(ui.title(f"Hello, {row.title}"), ui.meta("a preview"))

    def activate(self, row, mods):       # Enter; return True to close
        util.notify("Hello", row.data)
        return True

Layouts: "list" (rows, sections, preview), "grid" (cells, like the emoji picker) and "card" (build the whole panel in build_card()). See vyom/plugin.py for every hook (header_extra, key, opened, closed, live, anchor…), vyom/ui.py for widgets, and any tool repo for a worked example. Put it in ~/.local/share/vyom/plugins/hello (or a directory in $VYOM_PLUGIN_PATH) and vyom reload.

#Troubleshooting

• A tool doesn't open. vyom list shows every installed tool and why one is skipped (a missing requirement, or a Vyom too old for it).
• Something failed. The daemon logs to ~/.local/state/vyom/daemon.log; look for a Traceback. vyom quit; vyom <tool> restarts it.
• "Failed to initialize layer surface" / panels open as normal windows. gtk4-layer-shell has to load before GTK; vyom daemon does this itself through LD_PRELOAD, so start Vyom with vyom daemon, not python -m vyom.app.
• No blur or rounded corners. That's the compositor's part: on SwayFX use the layer_effects "vyom" block above; Hyprland: layerrule = blur, vyom.
• Icons show as boxes. Install a Nerd Font.

#Contributing

Bug reports, ideas and pull requests are welcome: see CONTRIBUTING.md for the development setup and the API rules, and CHANGELOG.md for what changed in each release. A problem with one tool belongs in that tool's repository. Please report security issues privately (SECURITY.md).

#License

MIT