1 +#
Quickshell Hypr Companions Phase 2A Bar Shell Implementation Plan 3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Add a hidden-by-default Quickshell top bar shell with Nugu styling, workspace buttons, and clock, without replacing Ironbar.
7 +**Architecture:** This is the first subplan of Roadmap Phase 2. It wires a per-monitor `Bar` into the existing Phase 1 `Scope`, controlled by IPC (`showBar`/`hideBar`/`toggleBar`) so it can be tested safely beside the current desktop. The bar uses Quickshell's Hyprland service for workspace active/occupied state and `SystemClock` for time.
9 +**Tech Stack:** Quickshell 0.3.0, QML/QtQuick, `Quickshell.Hyprland`, `SystemClock`, Nugu Theme service from Phase 1.
11 +**Roadmap:** [`docs/super/roadmaps/2026-06-17-quickshell-hypr-companions-roadmap.md`](../roadmaps/2026-06-17-quickshell-hypr-companions-roadmap.md)
13 +**Architecture Spec:** [`docs/super/specs/2026-06-17-quickshell-hypr-companions-architecture.md`](../specs/2026-06-17-quickshell-hypr-companions-architecture.md)
15 +**Parity Checklist:** [`docs/super/inventory/2026-06-17-quickshell-parity-checklist.md`](../inventory/2026-06-17-quickshell-parity-checklist.md)
17 +**Phase:** Phase 2A: Bar shell, workspaces, clock
23 +This plan intentionally implements only the safe first slice of Ironbar parity:
25 +- Top bar shell, hidden by default.
26 +- Nugu bar styling: height, padding, font, background, accent bottom border, hover/active/muted colors.
27 +- Workspace labels/actions for `1..5,9`.
28 +- Clock text `%H:%M`.
29 +- IPC to show/hide/toggle the bar for tests.
31 +Out of scope for this subplan:
33 +- Retiring or stopping Ironbar persistently.
34 +- Mako/notifications, tray, clipboard, bind mode, MPRIS, WiFi, Bluetooth, CPU, volume, brightness, battery, inhibit, power popup.
35 +- Hypr bind migration.
37 +Phase boundary: after this plan, Ironbar and Mako remain active. Quickshell can show a partial bar only on demand for visual and workspace testing.
43 +- `quickshell/nugu/Bar.qml` — per-monitor top bar shell and section layout.
44 +- `quickshell/nugu/BarButton.qml` — shared compact Nugu button primitive.
45 +- `quickshell/nugu/WorkspaceWidget.qml` — workspace row with labels, active/occupied/muted state, click-to-focus.
46 +- `quickshell/nugu/ClockWidget.qml` — center `%H:%M` clock.
50 +- `quickshell/nugu/shell.qml` — add `barVisible` state, IPC methods, per-monitor `Variants`.
51 +- `quickshell/nugu/README.md` — document Phase 2A IPC and safe test flow.
60 +##
Task 1: Add bar primitives 64 +- Create: `quickshell/nugu/BarButton.qml`
66 +- [ ] **Step 1: Write `BarButton.qml`**
68 +Create this file exactly:
76 + required property QtObject theme
77 + property string text: ""
78 + property bool active: false
79 + property bool muted: false
80 + property string tooltip: ""
84 + implicitWidth: label.implicitWidth + 14
88 + anchors.fill: parent
90 + color: root.active ? root.theme.ui.focus : (mouse.containsMouse ? root.theme.ui.accent : "transparent")
95 + anchors.centerIn: parent
97 + color: root.active || mouse.containsMouse
98 + ? root.theme.content.backdrop
99 + : (root.muted ? root.theme.ui.minor : root.theme.ui.normal)
100 + font.family: "IBM Plex Mono"
102 + font.bold: root.active
103 + font.features: { "tnum": 1 }
108 + anchors.fill: parent
110 + acceptedButtons: Qt.LeftButton
111 + onClicked: root.activated()
116 +- [ ] **Step 2: Run direct parse check expecting failure until shell wires files**
121 +timeout 3s qs -p quickshell/nugu/shell.qml
>/tmp/nugu-qs-2a-primitive.out
2>/tmp/nugu-qs-2a-primitive.err
; code
=$?; printf 'exit=%s\n' "$code"; sed -n
'1,120p' /tmp/nugu-qs-2a-primitive.err
124 +Expected: same result as Phase 1 (`124` and no QML errors) because the new file is not imported yet.
126 +##
Task 2: Add workspace widget 130 +- Create: `quickshell/nugu/WorkspaceWidget.qml`
132 +- [ ] **Step 1: Write `WorkspaceWidget.qml`**
134 +Create this file exactly:
138 +import QtQuick.Layouts
139 +import Quickshell.Hyprland
145 + required property QtObject theme
149 + property var workspaces: [
150 + { "id": 1, "label": "1 " },
151 + { "id": 2, "label": "2 " },
152 + { "id": 3, "label": "3 " },
153 + { "id": 4, "label": "4 " },
154 + { "id": 5, "label": "5 " },
155 + { "id": 9, "label": "9 " }
158 + function workspaceObject(id: int): var {
159 + return Hyprland.workspaces.values.find(workspace => workspace.id === id) || null
162 + function active(id: int): bool {
163 + return Hyprland.focusedWorkspace !== null && Hyprland.focusedWorkspace.id === id
166 + function occupied(id: int): bool {
167 + const workspace = workspaceObject(id)
168 + return workspace !== null && workspace.toplevels !== null && workspace.toplevels.values.length > 0
172 + model: root.workspaces
175 + required property var modelData
178 + text: modelData.label
179 + active: root.active(modelData.id)
180 + muted: !root.active(modelData.id) && !root.occupied(modelData.id)
181 + tooltip: `workspace ${modelData.id}`
183 + const workspace = root.workspaceObject(modelData.id)
184 + if (workspace !== null) {
185 + workspace.activate()
187 + Hyprland.dispatch(`workspace ${modelData.id}`)
195 +- [ ] **Step 2: Record API provenance in verification notes**
197 +Add this sentence to the eventual verification record for this phase:
200 +Workspace implementation uses Quickshell v0.3.0 `Hyprland.workspaces.values`, `Hyprland.focusedWorkspace`, `HyprlandWorkspace.toplevels.values`, and `HyprlandWorkspace.activate()` as documented in local Phase 2A planning.
203 +##
Task 3: Add clock widget 207 +- Create: `quickshell/nugu/ClockWidget.qml`
209 +- [ ] **Step 1: Write `ClockWidget.qml`**
211 +Create this file exactly:
221 + required property QtObject theme
223 + text: Qt.formatTime(clock.date, "HH:mm")
229 + precision: SystemClock.Minutes
234 +- [ ] **Step 2: Note Phase 2C calendar dependency**
236 +Do not add a calendar popup in this task. The Phase 2C plan owns popups and full clock/calendar parity.
238 +##
Task 4: Add top bar shell 242 +- Create: `quickshell/nugu/Bar.qml`
244 +- [ ] **Step 1: Write `Bar.qml`**
246 +Create this file exactly:
250 +import QtQuick.Layouts
257 + required property QtObject theme
258 + property bool shown: false
261 + anchors { top: true; left: true; right: true }
263 + color: "transparent"
266 + anchors.fill: parent
267 + color: `${root.theme.ui.backdrop}ee`
271 + anchors.left: parent.left
272 + anchors.right: parent.right
273 + anchors.bottom: parent.bottom
275 + color: root.theme.ui.accent
279 + anchors.fill: parent
280 + anchors.leftMargin: 20
281 + anchors.rightMargin: 20
282 + anchors.topMargin: 0
283 + anchors.bottomMargin: 2
287 + Layout.fillWidth: true
288 + Layout.alignment: Qt.AlignVCenter
291 + WorkspaceWidget { theme: root.theme }
295 + Layout.alignment: Qt.AlignCenter
298 + ClockWidget { theme: root.theme }
302 + Layout.fillWidth: true
303 + Layout.alignment: Qt.AlignVCenter | Qt.AlignRight
310 +- [ ] **Step 2: Check that bar remains unreachable until shell wiring**
315 +timeout 3s qs -p quickshell/nugu/shell.qml
>/tmp/nugu-qs-2a-bar-unwired.out
2>/tmp/nugu-qs-2a-bar-unwired.err
; code
=$?; printf 'exit=%s\n' "$code"; sed -n
'1,160p' /tmp/nugu-qs-2a-bar-unwired.err
318 +Expected: exit `124`, no QML parse/type errors.
320 +##
Task 5: Wire bar into shell IPC 324 +- Modify: `quickshell/nugu/shell.qml`
326 +- [ ] **Step 1: Replace `shell.qml` with bar-aware root**
328 +Replace the whole file with this content:
333 +import Quickshell.Io
339 + property bool diagnosticsVisible: false
340 + property bool barVisible: false
342 + Theme { id: theme }
347 + function showDiagnostics(): void { root.diagnosticsVisible = true }
348 + function hideDiagnostics(): void { root.diagnosticsVisible = false }
349 + function toggleDiagnostics(): void { root.diagnosticsVisible = !root.diagnosticsVisible }
351 + function showBar(): void { root.barVisible = true }
352 + function hideBar(): void { root.barVisible = false }
353 + function toggleBar(): void { root.barVisible = !root.barVisible }
355 + function reloadTheme(): void { theme.reload() }
356 + function setThemeMode(mode: string): void { theme.setMode(mode) }
360 + model: Quickshell.screens
361 + delegate: Component {
363 + required property var modelData
367 + shown: root.barVisible
373 + visible: root.diagnosticsVisible
379 +- [ ] **Step 2: Validate direct parse/start**
384 +timeout 3s qs -p quickshell/nugu/shell.qml
>/tmp/nugu-qs-2a-wired.out
2>/tmp/nugu-qs-2a-wired.err
; code
=$?; printf 'exit=%s\n' "$code"; sed -n
'1,200p' /tmp/nugu-qs-2a-wired.err
389 +- Exit `124` from timeout.
390 +- No QML parse/type errors.
391 +- No errors about `SystemClock.Minutes`, `Hyprland.workspaces.values`, or missing `BarButton` type.
393 +##
Task 6: Validate live IPC without retiring Ironbar 397 +- No tracked changes.
399 +- [ ] **Step 1: Start temporary named config**
401 +Run from repo root after Phase 1 link exists, or create the same symlink used by Phase 1:
404 +mkdir -p ~/.config/quickshell
405 +ln -sfn
"$PWD/quickshell/nugu" ~/.config/quickshell/nugu
406 +QS_NO_RELOAD_POPUP
=1 qs -c nugu
>/tmp/nugu-qs-2a-ipc.out
2>/tmp/nugu-qs-2a-ipc.err
& 407 +printf '%s\n' $!
>/tmp/nugu-qs-2a-ipc.pid
409 +sed -n
'1,160p' /tmp/nugu-qs-2a-ipc.err
412 +Expected: no QML parse/type errors. This does not use systemd and does not disable Ironbar.
414 +- [ ] **Step 2: Show bar**
419 +qs -c nugu ipc call nugu showBar
423 +Expected: Quickshell bar appears. Ironbar may still be visible; this is a temporary overlap test, not final visual approval.
425 +- [ ] **Step 3: Test workspace clicks visually**
427 +Manually click workspace buttons `1`, `2`, `3`, `4`, `5`, `9`.
431 +- Hyprland switches to clicked workspace.
432 +- Active workspace highlight changes immediately.
433 +- Empty workspaces are muted.
434 +- Occupied workspaces are normal foreground.
436 +- [ ] **Step 4: Test clock and theme switching**
441 +qs -c nugu ipc call nugu setThemeMode light
443 +qs -c nugu ipc call nugu setThemeMode dark
449 +- Bar colors change with Nugu mode.
450 +- Clock remains visible and formatted `HH:mm`.
452 +- [ ] **Step 5: Hide bar**
457 +qs -c nugu ipc call nugu hideBar
460 +Expected: Quickshell bar disappears; Ironbar remains live.
462 +- [ ] **Step 6: Stop temporary Quickshell**
467 +kill "$(cat /tmp/nugu-qs-2a-ipc.pid)" 468 +rm -f /tmp/nugu-qs-2a-ipc.pid
469 +ps -eo pid,pcpu,rss,comm,args
| grep -E
'qs -c nugu|quickshell' | grep -v grep
|| true
472 +Expected: no temporary `qs -c nugu` process remains.
474 +##
Task 7: Update README and verification record 478 +- Modify: `quickshell/nugu/README.md`
479 +- Create: `docs/super/inventory/2026-06-17-quickshell-phase-2a-verification.md`
481 +- [ ] **Step 1: Append Phase 2A README section**
483 +Append this to `quickshell/nugu/README.md`:
489 +The bar is hidden by default while Ironbar remains the live bar.
492 +qs -c nugu ipc call nugu showBar
493 +qs -c nugu ipc call nugu hideBar
494 +qs -c nugu ipc call nugu toggleBar
497 +Phase 2A only covers bar shell, workspaces, and clock. Full Ironbar parity requires later Phase 2B/2C plans.
500 +- [ ] **Step 2: Write verification record**
505 +mkdir -p docs/super/inventory
507 + printf '# Quickshell Phase 2A Verification — 2026-06-17\n\n'
508 + printf '## Commands\n\n'
509 + printf -- '- `timeout 3s qs -p quickshell/nugu/shell.qml`\n'
510 + printf -- '- `qs -c nugu ipc call nugu showBar`\n'
511 + printf -- '- `qs -c nugu ipc call nugu setThemeMode light`\n'
512 + printf -- '- `qs -c nugu ipc call nugu setThemeMode dark`\n'
513 + printf -- '- `qs -c nugu ipc call nugu hideBar`\n\n'
514 + printf '## Parse stderr\n\n```text\n'
515 + sed -n '1,200p' /tmp/nugu-qs-2a-wired.err 2>/dev/null || true
517 + printf '## IPC stderr\n\n```text\n'
518 + sed -n '1,200p' /tmp/nugu-qs-2a-ipc.err 2>/dev/null || true
520 + printf '## Manual observations\n\n'
521 + printf -- '- Bar appeared after showBar: recorded during execution.\n'
522 + printf -- '- Workspace buttons 1/2/3/4/5/9 switched Hypr workspaces: recorded during execution.\n'
523 + printf -- '- Workspace active/occupied/muted colors updated: recorded during execution.\n'
524 + printf -- '- Clock displayed HH:mm: recorded during execution.\n'
525 + printf -- '- Dark/light IPC changed bar colors: recorded during execution.\n'
526 + printf -- '- Ironbar remained live and was not retired.\n'
527 + printf -- '- Workspace implementation uses Quickshell v0.3.0 `Hyprland.workspaces.values`, `Hyprland.focusedWorkspace`, `HyprlandWorkspace.toplevels.values`, and `HyprlandWorkspace.activate()`.\n'
528 +} > docs/super/inventory/2026-06-17-quickshell-phase-2a-verification.md
531 +- [ ] **Step 3: Confirm old services still run**
536 +systemctl --user --no-pager --plain is-active ironbar.service ironbar-workspaces.service mako.service
539 +Expected: all three are still active.
541 +##
Task 8: Commit Phase 2A 545 +- Add/modify all files from prior tasks.
547 +- [ ] **Step 1: Check status**
555 +Expected: only intended Phase 2A files plus pre-existing unrelated dirty work.
557 +- [ ] **Step 2: Commit**
562 +git add quickshell/nugu/Bar.qml quickshell/nugu/BarButton.qml quickshell/nugu/WorkspaceWidget.qml quickshell/nugu/ClockWidget.qml quickshell/nugu/shell.qml quickshell/nugu/README.md docs/super/inventory/2026-06-17-quickshell-phase-2a-verification.md
563 +git commit -m
"feat(quickshell): add initial nugu bar shell" 566 +##
Task 9: Phase boundary check 570 +- No tracked changes unless verification found a bug.
572 +- [ ] **Step 1: Non-mutating final checks**
577 +hyprctl configerrors
578 +systemctl --user --no-pager --plain is-active ironbar.service mako.service
579 +ps -eo pid,pcpu,rss,comm,args
| grep -E
'ironbar|mako|workspaces-watch|qs -c nugu|quickshell' | grep -v grep
|| true
584 +- `hyprctl configerrors` empty.
585 +- Ironbar and Mako active.
586 +- No stray temporary `qs -c nugu` process unless explicitly left running for user review.
588 +- [ ] **Step 2: Report next subplan**
593 +Phase 2A adds hidden Quickshell bar shell/workspaces/clock only. Ironbar remains live. Next plan: Phase 2B status/service widgets.
596 +Do not start Phase 2B implementation in the same execution pass.
598 +##
Plan validation note 600 +Before implementation, the planned Phase 2A QML files were copied with Phase 1 `Theme.qml` and `hypr/generated/nugu.json` to a temporary `/tmp/pi-exp.qs-phase2a.*` directory and run with:
603 +timeout 3s qs -p /tmp/pi-exp.qs-phase2a.
*/quickshell/nugu/shell.qml
606 +Observed result on 2026-06-17: exit `124` from `timeout`, empty stderr, temp directory deleted. This supports the planned bar/workspace/clock QML parse/start shape on local Quickshell `0.3.0`.