Omarchy Agent Picker

A user-owned Omarchy shell overlay that opens a native agent picker before each coding-agent launch. It currently offers Claude Code, Codex, OpenCode, and Pi Mono. Hermes Agent and Amp Code are included as disabled entries that can be enabled when their CLIs are installed.

The project follows Omarchy's third-party shell-plugin contract:

• manifest.json is at the repository root;
• the plugin uses the namespaced ID ddebowczyk.agent-picker;
• AgentPicker.qml is a schemaVersion: 1 overlay entry point;
• runtime installation lives at ~/.config/omarchy/plugins/ddebowczyk.agent-picker/;
• the configurable Hyprland shortcut remains a user override in ~/.config/hypr/bindings.lua.

The overlay runs inside omarchy-shell. It uses Omarchy's themed layer-shell components, keyboard focus handling, and Quickshell.execDetached to start the selected command through omarchy-launch-tui.

Preview

Current setup

The current machine has:

• Omarchy theme: Hermarchy;
• default agent: codex;
• Claude Code installed through Omarchy's mise-backed launcher;
• shortcut Super + Shift + Ctrl + A overridden to open this picker.

The picker does not change the persistent Omarchy default agent. It launches the selected CLI with its normal interactive behavior.

Install or update

From this directory:

./install.sh

The installer copies the plugin into Omarchy's user plugin directory, seeds a user data file if one does not exist, validates the manifest, enables the plugin, installs the launcher command, and asks the running shell to rescan plugins.

Validation can also be run directly:

omarchy plugin validate ~/.config/omarchy/plugins/ddebowczyk.agent-picker
omarchy plugin list

Release a new version

Omarchy requires the plugin manifest to contain schemaVersion: 1 and a string version. The schema version identifies the manifest format; the release version follows MAJOR.MINOR.PATCH SemVer and belongs in manifest.json.

From a clean working tree, preview or create a release with:

./bin/release minor --dry-run
./bin/release minor
./bin/release patch --push
./bin/release 1.0.0 --push

The helper validates the plugin, updates only the manifest release version, creates a Release vX.Y.Z commit, and creates an annotated vX.Y.Z tag. It does not push anything unless --push is supplied. Omarchy itself updates git-managed plugins from the repository's branch, while the manifest version and git tag identify the release.

By default, the installer maintains this marked block in ~/.config/hypr/bindings.lua:

-- >>> omarchy-agent-picker managed binding >>>
hl.unbind("SUPER + SHIFT + CTRL + A")
o.bind("SUPER + SHIFT + CTRL + A", "Choose agent", "omarchy-agent-picker")
-- <<< omarchy-agent-picker managed binding <<<

Configure the activation shortcut

The live shortcut setting is:

~/.config/omarchy-agent-picker/config.json

Edit its shortcut value, for example:

{
  "version": 1,
  "shortcut": "SUPER + ALT + P"
}

Apply the change with either command:

omarchy-agent-picker-configure
./install.sh

omarchy-agent-picker-configure updates only the plugin-managed block, preserves other user bindings, migrates the original unmarked picker binding, and reloads Hyprland. Valid shortcut names may contain modifier combinations such as SUPER + SHIFT + CTRL + A, SUPER + ALT + P, or PRINT.

To restore the bundled shortcut setting:

./install.sh --reset-settings

If the binding is missing on another machine, run ./install.sh; it creates the user binding file when needed.

Configure agents

The live data file is:

~/.config/omarchy-agent-picker/agents.json

The source template is data/agents.json. Each enabled entry has:

{
  "id": "pi-mono",
  "label": "Pi Mono",
  "command": "pi",
  "args": [],
  "enabled": true,
  "description": "Pi terminal agent"
}

Add a custom agent

First verify that the CLI is installed and available to the launcher:

command -v my-agent
my-agent --version

Then add an entry to the live agents.json and set enabled to true:

{
  "id": "my-agent",
  "label": "My Agent",
  "command": "my-agent",
  "args": [],
  "enabled": true,
  "description": "My terminal coding agent"
}

args is an optional array of fixed arguments. Values are passed directly to the executable, without shell interpolation. When maintaining this project, add the same entry to data/agents.json so fresh installs include it. The live file is preserved by ./install.sh unless --reset-config is used.

Enable Hermes Agent or Amp Code

Install the relevant CLI separately, verify its command, then change its existing entry from "enabled": false to "enabled": true in the live file:

command -v hermes  # Hermes Agent
command -v amp     # Amp Code

The bundled entries use hermes and amp as their commands. If you do not use either CLI, leave the entries disabled or remove them as described in docs/configuring-agents.md.

Add, remove, or disable rows in the data file; no QML or shell-code change is needed. The plugin watches the live file. If the shell does not pick up a change immediately, run:

omarchy-shell shell rescanPlugins

command must name an executable available in the agent launcher's PATH. args is an optional array of fixed arguments. Arguments are passed directly, without shell interpolation.

To restore the bundled data template:

./install.sh --reset-config

For complete instructions, including how to add your own agent, hide an unused one, or remove it permanently, see docs/configuring-agents.md. Agents can also use the reusable guidance in skills/configure-omarchy-agent-picker/SKILL.md.

Manual controls

omarchy-agent-picker
omarchy-shell shell summon ddebowczyk.agent-picker '{}'
omarchy plugin enable ddebowczyk.agent-picker
omarchy plugin disable ddebowczyk.agent-picker

The first command is what the Hyprland shortcut runs. The second opens the overlay directly. Esc or clicking outside cancels; Up/Down, j/k, and the mouse move the selection; Enter launches it.

Security and Omarchy boundaries

Omarchy shell plugins run as unsandboxed code inside the long-lived omarchy-shell process. Review this plugin before sharing or enabling it. The picker passes data-file commands as argument-vector elements rather than through a shell command string, but those commands still run as the user.

This project only writes user-owned locations:

• ~/.config/omarchy/plugins/ddebowczyk.agent-picker/;
• ~/.config/omarchy-agent-picker/;
• ~/.local/bin/omarchy-agent-picker;
• the existing user Hyprland binding in ~/.config/hypr/bindings.lua.

It never edits /usr/share/omarchy/.

Session notes

See docs/session-notes.md for the work captured from the original setup session, including the Hermarchy background import and agent installation.