Quickshell MCP

Find real implementations of a FEATURE you want to build, described in plain words instead of exact type names: 'Hyprland workspace indicator', 'macOS-style control center', 'volume OSD', 'system tray', 'animated popup', 'floating notification', 'top bar with workspaces', 'launcher like Spotlight', 'power menu'. Searches Caelestia, Noctalia, and end-4's dots-hyprland (real-world shells) plus the official examples repo, interprets aliases ('Spotlight' means launcher, 'hud' means OSD), and returns a small ranked set where every entry carries source project, file path, why it matched, and the Qui…

Generate a minimal, source-grounded Quickshell QML component from a plain-language description, e.g. 'Create a Hyprland workspace indicator', 'animated volume OSD', 'top bar with workspaces, clock and system tray', 'popup control center', or 'notification popup'. The generator researches the request, assembles a small component from curated templates, and BEFORE returning it verifies every Quickshell type and property/method it references against the requested version (via the compatibility machinery) and runs the static validator on the assembled QML. Any API that cannot be verified is surfa…

Generate high-level panel scaffolding for a bar, OSD, launcher, dashboard, control center, or notification panel. This is scaffolding, not a full design generator: it reuses the component generator and project style detection, and outputs minimal, valid, extendable QML. Pass project= to align version, compositor, and conventions with the project.

Generate a generic, architecture-neutral Quickshell service abstraction for a common application concern. The first version returns a verified service skeleton with declared imports and a placeholder service object you can extend; it is deliberately generic rather than a giant library of service templates. No nonexistent Quickshell APIs are emitted. Pass project= to align the target version and compositor with the project.

Read one file from the official Quickshell examples repo verbatim (QML configs, READMEs). Get valid paths from quickshell_list_examples. Prefer these maintained examples over writing a shell config from memory.

Fetch one Usage Guide page as Markdown, e.g. slug='introduction' or slug='qml-language'. Call quickshell_list_guide_pages first if you don't know the exact slug. Defaults to the latest doc version.

Read a QML file from the Caelestia, Noctalia, or dots-hyprland shells (get paths from quickshell_search_implementations). Pass find='osd' / find='workspace' / find='ipc' etc. to jump to the most relevant section instead of pulling the whole large file. This is a real-world implementation reference, NOT official documentation: when it disagrees with quickshell.org or doc.qt.io, trust the docs.

Fetch one Qt type's reference page from doc.qt.io as Markdown, e.g. Rectangle, Text, MouseArea, Timer, Item, RowLayout, or a value type like color or vector3d. Use this when a Quickshell config imports QtQuick / QtQuick.Controls / QtQuick.Layouts types and you need their properties, signals, or syntax. Pass module (e.g. 'qtquick', 'qtquick-controls') to disambiguate names that exist in several modules. qt_version pins a minor (e.g. '6.8') to match your installed Qt instead of the newest.

Fetch the documentation page for one QML type as Markdown, e.g. type_name='PanelWindow', namespace='Quickshell', or type_name='HyprlandMonitor', namespace='Quickshell.Hyprland'. Call quickshell_list_types first if you're unsure of the exact namespace or type name (they are case-sensitive). Defaults to the latest doc version.

Inspect the Hyprland compositor read-only: monitors, workspaces, the active workspace, and clients, via ``hyprctl -j``. Returns an explanatory note when Hyprland/hyprctl is unavailable. Never modifies the compositor.

List files and folders in the official Quickshell examples repo (real-world sample shell/bar/widget configs written by the Quickshell authors). Call with no path to list the root, then drill into a folder using its path. Pair with quickshell_get_example to read a file's contents.

List the Usage Guide pages available for a given doc version (e.g. install-setup, introduction, size-position, qml-language, advanced, faq). Defaults to the latest version if none given. Set refresh=True to bypass the in-process cache.

List QML types documented on doc.qt.io for QtQuick and its sibling modules (Controls, Layouts, Effects, Shapes, ...), discovered from the QtQuick module page. Use this for Qt base types like Rectangle, Text, MouseArea, Timer, or RowLayout that Quickshell configs import but the Quickshell docs don't describe themselves. For Quickshell-specific types use quickshell_list_types instead. qt_version pins a minor (e.g. '6.8', '6.7') instead of the newest release. Set refresh=True to bypass the in-process cache.

List Quickshell QML types, optionally filtered to one namespace (e.g. 'Quickshell.Hyprland', 'Quickshell.Io', 'Quickshell.Services.Pipewire'). Call with no namespace to see every namespace and its types. Defaults to the latest doc version. Set refresh=True to bypass the in-process cache.

List all Quickshell documentation versions currently published on quickshell.org, newest first, and report which one is latest. Use this before fetching a page if you're unsure which version to use. Set refresh=True to bypass the in-process cache.

Migrate Quickshell/QML code from one Quickshell version to another: 'migrate this config from v0.2.0 to v0.3.0', 'what do I need to change to upgrade to the latest Quickshell?', 'is my config still valid after the upgrade?'. Analyzes the code (or a single API/type) against both versions and reports every removed, renamed, deprecated, or changed API, plus breaking changes from the changelog, each with severity, location, the old API, the replacement, why it must change, a suggested migration, confidence, and a cited source. Pass exactly one of: - code: the QML source to migrate - api: a dotted…

Migrate a whole project between Quickshell versions: summarize the API delta, run the per-file migration engine, and report confirmed breaking issues with sources. Read-only.

Detect the Nix infrastructure of a Quickshell project: flake.nix presence, devShells, nixpkgs inputs, and whether the flake is locked. File-based detection only (no nix evaluation). Falls back to the system package manager when no flake.nix is present. Read-only.

Optimize a project: profile a live session (when given) and run static component/binding/timer analysis plus a correlated diagnosis. Cost is never attributed without evidence. Read-only.

Compare how the indexed real-world shells (Caelestia, Noctalia, dots-hyprland) solve the same problem: per-project matches and source locations. Presents differences for comparison; never declares one implementation correct. Read-only.

Correlate static project evidence (bindings, timers, object tree) into prioritized performance hypotheses with evidence and confidence. Never modifies source. Read-only.

Inspect PipeWire read-only: sinks, sources, and device identity via ``pw-cli``. Returns a note when PipeWire/pw-cli is unavailable. Never changes device state.

Measure runtime characteristics of a managed session: CPU usage, memory (RSS), and sample duration via bounded /proc sampling. Reports methodology and limitations. Read-only.

Identify high-frequency or broad property bindings statically (potential re-evaluation chains). Static only; re-evaluation frequency needs runtime instrumentation. Read-only.

Identify components with potential performance concerns from static evidence: timer/animation counts and layout bindings. Never attributes cost without evidence. Read-only.

Delete a saved runtime profile from the in-memory registry by name. Mutates the profile registry only.

Export a saved runtime profile as a JSON-serializable dict (with its schema version), for backup or sharing between servers. Read-only.

Get a single saved runtime profile by name, with its full launch configuration and schema version. Read-only.

Import a runtime profile into the registry from a dict (e.g. the output of quickshell_profile_export). A payload with a newer schema version than this server supports is refused. Mutates the profile registry only.

List all saved runtime profiles with summary info: name, project root, entrypoint, compositor, and schema version. Read-only.

Report object-tree statistics from static QML structure: total objects, repeated component patterns, and nesting depth. Useful for optimization; large trees are not automatically bad. Read-only.

Save a named runtime launch profile in this server's in-memory registry. Profiles are pure data (never launched by saving); combine them with quickshell_runtime_start. Mutates the profile registry only.

Find timers with potentially suspicious configuration (very short intervals, repeat disabled). Frequent timers are not labeled bugs by themselves. Read-only.

Inspect a Quickshell project and produce a structured project overview containing, where detectable: Quickshell version, Qt version, entrypoints, QML files, JS files, imports, Quickshell modules, components, services, compositor integrations, runtime dependencies, and project configuration. Builds on the shared ProjectContext. Unknown or undetected values are explicitly marked; no information is fabricated. File listings are capped to a reasonable sample; the full list is available via the specialized project tools.

Produce evidence-backed architecture recommendations for a project: confirmed cycles, unresolved references, and docs-grounded guidance. Every recommendation cites its evidence and basis. Read-only.

Analyze a whole project's Quickshell API compatibility against a target version: unavailable, deprecated, or changed APIs with affected files and concrete locations. Reuses the version compatibility engine. A verdict of 'uncertain' means the docs did not prove availability either way — it is never reported as a runtime incompatibility.

Detect a Quickshell project's configuration conventions: entrypoints, configuration files, environment variables, structural conventions, and runtime hints. Inferred values include confidence levels; directly observed values carry high confidence.

Detect a Quickshell project's dependencies from source and configuration, without executing anything. Classes are: - required: Quickshell and Qt modules the project imports - optional: imports that match known namespaces without local files - detected: runtime hooks, services, config keywords, environment variable references - missing: imports that resolve to neither a known namespace nor a local component

Project-aware search: find where a concept, API, type, or property is used in a Quickshell project. Supports both exact textual matching and semantic/project-aware matching (type names, import modules). Returns file, location, match context, and why the result matched. Exact textual matches are ranked first; semantic matches follow.

Run quality-oriented lint checks across a Quickshell project. Every rule has a stable diagnostic code, severity, explanation, and remediation. Rules are conservative and evidence-based; they flag suspicious patterns (duplicate imports, duplicate object ids, suspicious timers) rather than subjective style opinions. The rule table is extensible for future additions.

Build a machine-readable project graph showing relationships between QML components, imports, service dependencies, entrypoints, and module dependencies. Relies on reliable static relationships. The output clearly distinguishes: - confirmed relationships (directly observed import statements, type matches against local file stems) - inferred relationships (references that could not be proven local) Reports cyclic component usage and references that match no local file and no known namespace.

Project memory: explicit, evidence-backed notes about a project (13.1). action= is one of save (store a keyed entry with evidence), list (summarize), get (one entry), clear (one key), or reset (all). Memory is session-scoped, inspectable, and resettable. Read-only except the registry mutations it performs.

Analyze a whole Quickshell project for what must change to move from one Quickshell version to another: breaking and deprecated APIs, required changes, and a machine-readable proposed-edit list. Never modifies files. Every proposed edit carries file, line, and old/new API context so it can be applied safely. Reuses the existing migration engine per file.

Run the static QML validator across an entire Quickshell project and aggregate syntax errors, import problems, type problems, property and signal issues, version mismatches, and deprecated or unavailable APIs. Results are grouped by file and severity. One bad file never prevents analysis of the rest: unreadable files are reported and skipped. Reuses the existing validator rather than duplicating logic.

Return provenance for knowledge results: source, version, URL, and authority level (docs > examples > real-world), so higher-level results can cite them. Read-only.

Propose a safe refactoring (rename component, property, or reference) across a Quickshell project: rename an identifier everywhere it appears as a whole token. Returns structured edits plus a unified diff. Never writes files — apply the edits with quickshell_apply_patch when you are ready.

Detect regressions by comparing the current state against a baseline: validation of every QML file plus an optional screenshot comparison. Only confirmed changes are reported; absent baselines are surfaced, not fabricated. Read-only.

Reload a managed runtime session, preserving session tracking. Reuses the lifecycle implementation; cleans up after failed reloads. Never touches production Quickshell processes. Mutating.

Correlate evidence into a root cause, separating inferred hypotheses from observed evidence. Combines static doc-grounded explanation with live runtime diagnosis; never fabricates a cause without evidence. Read-only.

Detect what a Quickshell project needs at runtime, statically and safely: QML types (Process, IpcHandler, ...), config keywords, imports, compositor, services, and which system binaries are on PATH. Nothing is executed. Read-only.

Diagnose a managed runtime session: combine runtime logs, errors, project context, and version info into a probable root cause with confidence. Never fabricates a cause when evidence is insufficient. Read-only.

Extract and normalize common Quickshell/QML runtime problems from a session's stderr: import failures, undefined properties, type mismatches, binding loops, component load failures, JS exceptions, and signal/method errors. Original error text is preserved. Read-only.

Return structured logs from a runtime session with optional filtering by stream (stdout/stderr), text, and a bounded limit. Read-only.

Lightweight readiness/health check for a runtime session. Distinguishes: process_running, exited (with exit code), or unhealthy. Fast, read-only.

Reset a managed runtime session to a clean state. Stops the current session, cleans up its isolated temp dirs, and starts a fresh session with the same profile under a new session id. Mutating.

Start a managed, isolated Quickshell runtime session for a project. Launches ``qs`` with isolated XDG directories so it never touches your real desktop session or other quickshell instances. Returns a session id and tracks the process for later status, logs, ping, stop, and reset. This is a mutating operation: it launches a process.

Return structured status for a runtime session: session id, running state, PID, startup duration, exit code, and profile identity. Read-only.

Stop a managed runtime session safely (SIGTERM, then SIGKILL on timeout). Handles already-exited and orphaned processes; stops only the tracked session's process group, never unrelated user processes. Mutating.

Capture a bounded screenshot of a managed Quickshell runtime session. Requires the ``grim`` compositor screenshot tool on PATH. **Full-desktop capture is disabled by default.** Pass ``rectangle=`` with ``x``, ``y``, ``width``, ``height`` to target a specific region. Object-derived geometry is not yet available and will report an explanatory note. Set ``QUICKSHELL_DOCS_MCP_ALLOW_FULLSCREEN_CAPTURE=1`` at server launch to allow full-screen captures (high-risk: includes all desktop content). Read-only.

Compare two runtime screenshots with ImageMagick ``compare``. Returns whether they differ, the diff image path, and a metric. Deterministic for CI. Read-only.

Capture a region-based screenshot of a managed runtime, preferring an object-derived region over manual coordinates. Read-only; requires grim. Pass ``rectangle=`` (x, y, width, height) to capture a bounded region. Full-desktop capture is disabled by default; object-derived geometry requires a compositor adapter (reports an explanatory note).

Search Quickshell type names, namespaces, and guide page slugs for a substring match (case-insensitive). ALWAYS call this before writing any QML that references a Quickshell type or property from memory; never guess property/type names, verify them here first. Use this whenever a request mentions a desktop-shell feature and you don't already know the exact Quickshell type name, e.g.: - "battery" / "power" / "upower" -> search 'battery' or 'power' (UPower, UPowerDevice) - "volume" / "audio" / "mixer" -> search 'audio' or 'volume' (Pipewire, PwNode) - "tray" / "system tray" …

Search ALL sources at once with one natural-language query: Quickshell docs (type names, guide pages), Qt/QML types on doc.qt.io, official example configs, and real-world implementations (Caelestia, Noctalia, and end-4's dots-hyprland). Results come back grouped by source, most relevant group first; every entry carries a relevance score, a why-it-matched reason, and a URL or repo path. Use this when you don't know which specialized tool fits ("how do I make a workspace bar?", "create a volume OSD") or as a first pass before drilling in. API-shaped queries ("PanelWindow", "exclusive zones") ra…

Search real-world Quickshell shells (Caelestia, Noctalia, and end-4's dots-hyprland) for implementations: 'find a bar implementation', 'find a control center example', 'find Quickshell IPC usage', 'find multi-monitor implementation', 'find workspace widget', 'find notification/OSD/launcher implementation', 'find lock screen', 'find wallpaper handling', 'find Quickshell animations', 'find service patterns', 'find reusable QML components', 'find Hyprland/Niri integration', 'find volume/audio implementation', 'find wifi/network implementation', 'find bluetooth', 'find brightness', 'find battery i…

Report session usage stats for this MCP server: per-tool call counts, network fetches vs cache hits, and process uptime. Use this to check how much the server has been consulted and how much it hit the live site vs its 30-minute cache.

Analyze an existing Quickshell project and infer reusable UI conventions: colors, corner radius, font sizes, spacing, animation durations, component structure, and naming patterns. Returns evidence-backed findings (values actually present and their frequency), never design opinions. Generation tools can consume this style representation later.

Report verified-only environment problems for Quickshell development: missing commands and services. Only evidence-backed issues are reported. Read-only.

Plan a development request with the minimal tool set: inspect the project first, select the fewest tools that accomplish the intent, and stop when verification would confirm the change. Advisory and read-only; planning never executes anything.

Run a single machine-readable runtime test against a managed Quickshell session. A test has a name, a list of steps (wait, invoke, set_property), and a list of assertions (object_exists, property_equals, property_contains, property_matches, visible, enabled, text_matches, window_exists). Returns pass/fail, per-step and per-assertion results, duration, and an optional screenshot on failure. Mutating (drives the runtime).

Test a feature end-to-end: start an isolated Quickshell session, run the machine-readable test suite, capture a screenshot on failure, and stop the session. Mutating (launches and stops a session).

Define or retrieve a reusable parameterized runtime macro: a named sequence of safe runtime steps that tests can invoke. Pass steps= to save a macro; omit steps to load one by name. Macros are project-scoped for the process. Read-only.

Record a list of runtime actions into a reproducible test representation. Uses stable selectors (target + method/property), not fragile generated object ids. Read-only.

Produce a structured test report: passed/failed tests, durations, assertions, runtime logs, screenshots, and diagnostics. Suitable for both an LLM and human CI output. Read-only.

Run multiple named runtime tests in isolation. One failing test never corrupts the rest of the suite. Returns pass/fail totals and per-test results. Mutating.

Trace a selected runtime interaction across observable state transitions. Reports observed log events; inferred transitions are always kept separate from observed evidence. Read-only.

HIGH-RISK: evaluate QML/JavaScript in a managed runtime session. Explicitly opt-in, session-scoped, with an execution timeout and output limits. No filesystem or process access is granted. Prefer quickshell_ui_get_property / quickshell_ui_invoke for controlled reads and calls.

Search the live QML object tree of a managed runtime session by name, type, text, or property. Returns stable references for later runtime tools. Read-only.

Read a live QML property value from a managed runtime object via ``qs ipc prop get``. Validates the object/property exist. Read-only.

Invoke a QML method on a managed runtime object via ``qs ipc call``. Mutating. Validates the method and arguments; enforces runtime session boundaries; no arbitrary process/system calls.

Set a live QML property on a managed runtime object. Mutating. Requires an explicit runtime session, validates the property exists, returns the old and new values, and never modifies project files.

Create a single serializable UI snapshot: screenshot, UI tree, live properties, runtime state, timestamp, and project metadata. Comparable for regression detection. Read-only. Pass ``rectangle=`` to capture a bounded screenshot region; full-desktop capture is disabled by default (see quickshell_screenshot).

Inspect the live QML object tree of a managed runtime session. Returns a compact, depth-limited hierarchy from the injected 'inspector' IpcHandler target. Read-only.

Statically validate Quickshell/QML source before you run it: unknown types, unknown properties, unknown signals, missing imports, obvious type mismatches, and APIs not available in the requested Quickshell version. Pass the QML source; optionally pin a Quickshell version (defaults to the latest) and give a filename so a root type matching the file stem is treated as a local component instead of an unknown type. The check is a lightweight heuristic that complements qmlls, not a replacement: it validates types/properties/signals against the Quickshell and Qt docs, skips JavaScript bodies, and …

Analyze a runtime screenshot for objective UI problems: clipping, overflow, missing expected elements, unexpected empty areas, misalignment, or off-screen content. Returns observations with confidence and affected regions. It does not claim to prove semantic correctness. Read-only. Pass an explicit screenshot_path to analyze an existing file, or rectangle= to capture a bounded region. Full-desktop capture is disabled by default (see quickshell_screenshot).

Compare baseline and actual screenshots deterministically for visual-regression testing: diff image, differing pixels metric, configurable threshold, and ignored regions. Read-only.

Inspect Wayland layer/surface information for the managed runtime. Requires a compositor adapter; reports a note when unavailable. Read-only.

Enumerate windows/surfaces belonging to a managed Quickshell runtime session. Read-only. Requires a compositor adapter; when unavailable returns an empty list with an explanatory note (never fails).