Quickshell MCP

Fetch the Quickshell 'About' page (https://quickshell.org/about/) as Markdown. Use this for high-level questions like what Quickshell is, who maintains it, and how it's licensed.

Compare two Quickshell versions and report added, removed, renamed, and deprecated APIs, each with provenance (changelog and type-page URLs). Read-only.

Build a documented API dependency graph for a type: its declared properties (with their types) and its documented base type. Only documented relationships are included — no speculative edges. Read-only.

Apply a previously generated edit set to a Quickshell project, but only when explicitly requested. This is a mutating operation. Validates that every edit path stays inside the authorized project root, the patch is well-formed, not stale (optionally by expected file hashes), and would not silently overwrite conflicting edits. Only whole-token occurrences are replaced, and a target must be unique or the patch is rejected. Reports every changed file. Nothing outside the project root is ever touched.

Run a single reusable assertion primitive against a managed runtime session: object_exists, property_equals, property_contains, property_matches, visible, enabled, text_matches, window_exists. Returns a structured pass/fail with useful context. Read-only.

Return evidence-backed implementation guidance ranked by authority: official docs > official examples > real-world shells. Documented behavior is separated from community convention. Read-only.

Inspect a binding on a managed runtime object: current live value, likely source expression (from the project QML), and files that reference it. Read-only.

Build a feature end-to-end: analyze the project, research the APIs, generate a verified component, validate it, and optionally apply a permitted edit set. Returns the full staged plan. Read-only unless apply=True and an explicit edit set is given (then mutating).

Fetch the Quickshell changelog (https://quickshell.org/changelog/) as Markdown. Use this to answer 'what's new / what changed' questions.

Check whether a Quickshell API, QML property/method/signal, type, or code snippet is compatible with a specific Quickshell version. Use this before targeting an older release, e.g. 'is PanelWindow.exclusiveZone available in v0.2.0?', 'which version introduced SomeType?', 'does this QML config work on v0.3.0?', 'was Quickshell.shellRoot renamed?'. Pass exactly one of: - api: a dotted path like 'PanelWindow.exclusiveZone', 'Quickshell.Hyprland.HyprlandMonitor', or 'HyprlandWorkspace.activate()' - type: a bare type name like 'PanelWindow' - code: a QML snippet; every referenced type and property is checked version pins the Quickshell release (default 'latest', resolved at runtime). to_version overrides version as the target; from_version adds a lower-bound so the result reports compatibility across the whole range. The verdict is one of 'compatible' / 'incompatible' / 'uncertain', backed by per-version documentation and changelog evidence (never a guess from the latest page alone). Qt/QML types (Rectangle, Item, ...) are reported as compatible with origin 'qt': their availability is governed by your Qt version, not the Quickshell one.

High-level Quickshell development assistant for AI coding agents. Give it one plain-language development request and it routes the work through the other tools, returning a structured, source-grounded result: - build: 'build a Hyprland workspace bar', 'add an animated volume popup' - debug: 'why is this PanelWindow failing?', 'fix this QML error' (pass error= and/or code=) - migrate: 'migrate this shell from v0.2 to v0.3' (from_version/to_version pin the range) - adapt a pattern: 'find an implementation of this feature and adapt it' - research: 'how should I structure this component?', 'what is PanelWindow?' The assistant picks the minimal set of lower-level tools needed (search, pattern lookup, type/guide pages, compatibility, migration, generation, validation), runs each step in isolation so a failing source never sinks the whole answer, deduplicates searches, reuses the shared cache, and never modifies files. version pins the Quickshell release. Results clearly separate verified facts (official docs) from recommendations, and every claim carries a source URL. For a single, focused lookup call the specific tool directly instead. Pass project= a path to the Quickshell project root to ground the answer in that project: the assistant infers its Quickshell version and compositor from the project's QML imports and uses them as defaults, and returns a 'project' section describing what was detected (version, compositor, QML files, each marked detected/inferred/unknown). An invalid path is reported in that section instead of failing the request. Execution is off by default: the assistant never modifies files. To let it apply an explicit, validated edit set to the project, pass permitted_execution=True together with edits=[...] (same shape as quickshell_apply_patch) and a project= path. Non-permitted requests record an execution step and continue read-only.

List user-session D-Bus services read-only via ``busctl``. Discovery only — method invocation is never performed. Read-only.

Debug a failure end-to-end: explain the error from the docs, then correlate live runtime evidence (errors, diagnosis, trace, binding) when a session id is given. Inferred causes are kept separate from observed evidence. Read-only.

Run the full engineering loop end-to-end: build → test → debug → optimize → verify, composing the agent tools with per-stage isolation so one failing stage never sinks the rest. Pass tests= a machine- readable suite to enable the test stage; the loop is otherwise read-only. Returns every stage's result plus the flattened plan.

Explain a Quickshell/QML error and suggest a fix, grounded in the actual documentation. Pass the error message; optionally include QML code, the filename, line number, component/type name, or Quickshell version for a more precise diagnosis. The tool verifies reported properties, methods, and signals against the Quickshell and Qt type indexes before suggesting fixes, so it never recommends APIs that don't exist. Use this when you encounter errors like: - "Cannot assign to non-existent property" - "Type 'X' is not accessible" - "X is not a function" - "Cannot connect to non-existent signal" - "module 'X' is not installed" - "Invalid assignment" - "Could not find or load the component" - binding errors or type mismatches

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 Quickshell APIs that pattern typically needs. When several projects solve the same pattern they are grouped so you can compare approaches. For API/type lookups by name use quickshell_search or quickshell_search_all instead; for browsing one repo use quickshell_search_implementations. Read matched files via quickshell_get_implementation / quickshell_get_example. limit caps total implementations (default 5, max 10); version pins a Quickshell release; refresh=True bypasses the cache.

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 surfaced rather than silently emitted, so the result never claims an API is valid without checking. The result also includes a 'verified_surface': the documented properties/methods/signals of every type the component uses, so you can freely rewrite the QML against verified members. When no curated template matches the request, the result carries that verified surface plus supporting references instead of a component, so you can compose the component yourself from grounded building blocks. Only one top-level window is generated; additional requested windows are reported in 'assumptions' rather than embedded. Inputs: - description: what to build, in plain words - version: Quickshell release to target (default 'latest', resolved at runtime) - compositor: e.g. 'hyprland' to use compositor-specific types - style: optional style/behavior hints (surfaced in 'assumptions') - context: optional existing project context (surfaced, never read) - filename: suggested filename; derived from the description by default The result includes the generated QML, the imports/types it needs, any compositor or external-service dependency, per-API verification evidence, validation diagnostics, supporting references, and the assumptions made. Official documentation always wins over examples and real-world implementations when they disagree. This tool writes nothing to disk. Pass project= a path to the project root to make generation project-aware: the target version and compositor default to the project's detected values, and detected conventions are surfaced as assumptions.

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 path like 'Quickshell.shellRoot' or 'PanelWindow.exclusiveZone' - type: a bare type name like 'LegacyThing' Both from_version and to_version are required. The scan covers only breaking-change changelog entries between the versions that mention the referenced symbols, so a rename that landed at an intermediate release is reported with the version it landed in, not as a vague 'sometime between'. Findings are classified definite / likely / manual_review: only changes backed by the docs or changelog are definite. This tool analyzes and recommends; it never rewrites code or modifies files.

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.