Omarchy Board

Omarchy Board teaches you keyboard shortcuts while you work. It shows a small, useful set for the app in front of you. Dismiss what you know; the next suggestion takes its place.

It learns from your system, follows you between apps, and gets out of the way as you learn.

Contexts

The first release includes:

• Chromium-family browsers, including Brave, Chrome, Chromium, Edge, and Vivaldi
• Herdr using the active bindings from ~/.config/herdr/config.toml
• Lazygit using its fully merged lazygit --config keymap
• Lazydocker using defaults pinned to the detected installed version
• Tmux using the running server's effective prefix and key table
• Vim and Neovim
• Common interactive shell editing
• GNOME Files
• Obsidian with per-vault hotkey overrides
• Postman using accelerators extracted from the installed application build
• User-assigned Chromium/Brave extension shortcuts
• A curated selection from the live Omarchy/Hyprland keybinding inventory

Nested terminal contexts are supported. When Neovim is focused inside Herdr, the board shows Neovim first, Herdr navigation second, and Omarchy shortcuts last.

Install

omarchy plugin add https://github.com/timothygwright/omarchy-board.git --enable

The plugin adds a keyboard button to the Omarchy bar and opens the independent board on the left side of the focused monitor. A native first-run screen explains local data access, lets you choose reserved or overlay layout, and introduces the learning controls before suggestions appear.

Use

• Select the x beside a suggestion to mark it as learned.
• Select the learned count at the bottom of the board to restore all shortcuts.
• Left-click the bar button to hide or show the board for the current session.
• Middle-click the bar button to refresh the context immediately.
• Right-click the bar button to restore all learned shortcuts.

Learned shortcuts are stored in:

~/.local/state/omarchy-board/dismissed.json

First-run completion is stored alongside it in setup.json. Remove that file or run the collector's setup-reset command to show onboarding again.

Settings

Open Omarchy's plugin settings to configure:

• Edge: left, right, top, or bottom
• Layout: reserve workspace space or overlay windows
• Focus delay: how long focus must remain on another monitor before moving
• Width for left and right edges
• Height for top and bottom edges
• Maximum suggestions shown per context
• Transparent background

The default is a 220-pixel reserved board on the left edge with a 500ms monitor focus delay. Reserved mode necessarily resizes tiled windows when the board moves between monitors. Use overlay mode to avoid workspace reflow.

Detection

Omarchy Board uses this precedence for every context:

1. Live application state or application API
2. The user's effective application configuration
3. Defaults reported by the installed application
4. A bundled fallback when the application exposes no machine-readable source

Bundled profiles choose the useful actions and provide fallback labels. They do not override a key reported by the user's system. The board identifies each group as live, configured, or fallback so its provenance is visible.

The collector reads local system state only:

• hyprctl activewindow -j and hyprctl monitors -j
• A bounded child-process walk under the focused terminal PID
• herdr pane current and herdr pane process-info when Herdr is active
• lazygit --config when Lazygit is active
• tmux show-options and tmux list-keys when Tmux is active
• omarchy menu keybindings --print
• ~/.config/herdr/config.toml
• Brave's ~/.config/BraveSoftware/Brave-Browser/Default/Preferences or Chromium's ~/.config/chromium/Default/Preferences for user-assigned extension commands
• Obsidian's ~/.config/obsidian/obsidian.json to identify the active vault
• The active Obsidian vault's .obsidian/hotkeys.json
• Postman's installed native-menu definitions, cached by build modification time

The Omarchy inventory is cached for 30 seconds. There is no network access, background daemon, privilege escalation, or shortcut execution.

Command output is capped while each command runs, and both commands and the overall context collector have kill deadlines. Local configuration reads are byte-bounded, require regular files, and do not follow symlinks. Plugin-owned state and cache directories are user-owned with 0700 permissions; their files are written with 0600 permissions using directory-relative atomic replaces.

Development

omarchy plugin validate .
python3 -m unittest discover -s tests -v
python3 -m py_compile bin/omarchy-board-context
qmllint -I /usr/share/omarchy/shell Service.qml BoardWindow.qml BarWidget.qml

Requirements

• Omarchy Quattro with the Omarchy Shell plugin system
• Python 3.11 or newer
• Optional application CLIs such as herdr, lazygit, tmux, and lazydocker are queried only when their matching application is active

The plugin requires no additional packages, network access, elevated privileges, or background system service.

Privacy and capabilities

Omarchy Board runs as an unsandboxed Omarchy Shell plugin. It reads only local state needed to resolve shortcuts: focused-window metadata, bounded process information for the focused terminal, supported application configuration, and installed application defaults. It launches read-only application commands such as herdr pane current, lazygit --config, and tmux list-keys when the matching application is active.

The plugin writes only to ~/.local/state/omarchy-board, ~/.cache/omarchy-board, and its own entry in Omarchy's shell.json after an explicit setup choice. It does not modify application keymaps, execute shown shortcuts, transmit data, request elevated privileges, or install a service.

Remove

omarchy plugin remove io.github.timothygwright.omarchy-board

To remove learned/setup state as well:

rm -rf ~/.local/state/omarchy-board ~/.cache/omarchy-board

Plugin source changes hot-reload when installed normally under ~/.config/omarchy/plugins/. A development symlink may require omarchy restart shell because the shell watcher does not follow the symlink target.

License

MIT. See LICENSE and THIRD_PARTY_NOTICES.md.