plugin-quickshell

Placement	runtime (out-of-process over gRPC)
Source	github.com/opencharly/plugin-quickshell/candy/plugin-quickshell
Version	2026.243.1500
Candy	plugin-quickshell

This plugin is not listed in charly/charly.yml’s compiled_plugins:. It is not part of the shipped binary: charly builds and loads it out-of-process over gRPC when a plan references one of its words (the coexist path).

Providers

The reserved words this plugin serves:

• quickshell — verb class

What it does

OUT-OF-TREE charly plugin serving the quickshell live-deployment check verb — a standalone Go module driving the IPC channel of a Quickshell desktop shell over go-plugin gRPC via the charly plugin SDK. charly’s loader fetches this candy’s repo, go-builds the provider binary on the HOST, and serves it OUT-OF-PROCESS, so the quickshell: verb dispatches through the provider registry exactly like a built-in. . WHY IT IS A VERB AND NOT A command: STEP. Quickshell’s qs ipc reports IPC-level failures — “Target not found.”, “Function not found.”, argument-count errors — on STDOUT while exiting ZERO. A command: step asserting “the menu opened” therefore passes against a shell with no menu plugin loaded, against a typo in the target name, and against an IPC surface that changed underneath it: green, asserting nothing. This verb reads those responses and fails on them, which is the entire difference between the two. . DESKTOP-AGNOSTIC BY CONSTRUCTION. It speaks Quickshell’s IPC, not any one desktop’s vocabulary: config: names the shell directory and target:/function: name whatever that shell’s QML exposes. Omarchy is one caller; the failure strings the verb keys on live in the quickshell binary itself.

Parameter schema

The CUE schema below is the authoritative grammar for this plugin’s input. It is the same single source that generates the plugin’s Go parameter types and answers the runtime Describe RPC, so this page cannot disagree with either.

schema/quickshell.cue

// This plugin's OWN CUE schema — the typed plugin_input for the `quickshell`
// live-deployment check verb, served over the Describe channel. It is the SINGLE
// SOURCE for this plugin's params, used two ways (the contract core `spec` and the
// reference plugin-http use):
//
//  1. GENERATE the Go param struct — `cue exp gengotypes` emits ../params/cue_types_gen.go,
//     so the provider decodes plugin_input into a TYPED struct, never a hand-parsed map.
//  2. VALIDATE authored input AT RUNTIME — the host splices this source onto the base
//     and validates every authored `quickshell` step's plugin_input against #QuickshellInput.
//
// SELF-CONTAINED: it references NO base def, so it compiles standalone AND splices onto
// the base. The shared step matchers (exit_status/stdout/stderr) stay on core #Op.
#QuickshellInput: {
  // method — what to do with the shell's IPC.
  //
  //   call  the generic primitive: invoke `function` on `target` with `args`
  //   ping  the liveness convenience — `call` against the shell's own ping
  //
  // The set is deliberately small. Quickshell's IPC surface is `call` plus the
  // listen/wait/prop streaming forms; a check verb wants request/response, and
  // everything a desktop exposes is reachable through `call`.
  method: "call" | "ping"
  // config — the Quickshell config DIRECTORY (`qs ipc -p <dir>`), i.e. the folder
  // holding shell.qml. REQUIRED: `qs` matches instances by config path, and a caller
  // from outside the session has no ambient one. Omarchy's is /usr/share/omarchy/shell.
  config: string & !=""
  // target — the IpcHandler target name. Defaults to "shell" for `ping`.
  target?: string
  // function — the IpcHandler function to invoke. Required for `call`.
  function?: string
  // args — positional arguments passed after the function name. A JSON payload is
  // just a string argument, e.g. '{"menu":"root"}'.
  args?: [...string]
  // wayland_display — the WAYLAND_DISPLAY to talk to. Empty means "discover it from
  // XDG_RUNTIME_DIR", which is what a step running over SSH needs: qs matches
  // instances by display and an SSH session has none.
  wayland_display?: string @go(WaylandDisplay)
}

---

See also the candy reference for this candy’s install surface.