Add desktop sidecar for live queue visibility

.gitignore

@@ -37,3 +37,7 @@ thoughts/
 # IntelliJ Plugin
 intellij-plugin/build/
 intellij-plugin/.gradle/
+
+# Desktop sidecar
+desktop-sidecar/build/
+desktop-sidecar/.gradle/

README.md

@@ -120,6 +120,32 @@ With the queue:
 - **Zombie Protection**: Detects dead processes, kills orphans, clears stale locks
 - **Auto-Kill**: Tasks running > 120 minutes are terminated
 
+## Desktop Sidecar
+
+The repo also includes a minimal Compose Multiplatform desktop app in [desktop-sidecar](desktop-sidecar/README.md) for watching the queue in real time.
+
+It reads the same local SQLite database as `tq` and the IntelliJ plugin, then shows:
+
+- running tasks
+- waiting tasks
+- exact queues grouped by their root scope (for example `gradle/build` and `gradle/emulator-5554` under `gradle`)
+
+Run it with:
+
+```bash
+cd desktop-sidecar
+./gradlew run
+```
+
+Or point it at a different queue data directory:
+
+```bash
+cd desktop-sidecar
+./gradlew run --args="--data-dir /path/to/agent-task-queue"
+```
+
+The sidecar defaults to `$TASK_QUEUE_DATA_DIR` or `/tmp/agent-task-queue`. It visualizes live occupancy from `queue.db`; configured `--queue-capacity` limits are process-local and are not stored in SQLite, so the UI shows live tasks and queue topology rather than persisted capacity settings.
+
 ## Installation
 
 ```bash

desktop-sidecar/README.md

@@ -0,0 +1,36 @@
+# Agent Task Queue Desktop Sidecar
+
+Minimal Compose Multiplatform desktop app for watching the local `agent-task-queue` database in real time.
+
+The sidecar reads the existing SQLite queue DB directly and shows:
+
+- running tasks
+- waiting tasks
+- exact queues grouped by root scope so hierarchical queue activity is easier to understand
+
+It is intentionally read-only. There is no new MCP protocol or server surface.
+
+## Run
+
+```bash
+./gradlew run
+```
+
+By default the app reads `$TASK_QUEUE_DATA_DIR` or `/tmp/agent-task-queue`.
+
+Use a specific queue directory with:
+
+```bash
+./gradlew run --args="--data-dir /path/to/agent-task-queue"
+```
+
+## Package
+
+```bash
+./gradlew packageDistributionForCurrentOS
+```
+
+## Notes
+
+- `./gradlew` in this directory delegates to the checked-in Gradle wrapper under `../intellij-plugin/` so the sidecar stays lightweight.
+- Queue capacities configured with `--queue-capacity` are process-local and are not persisted in `queue.db`, so the app visualizes live tasks and queue layout rather than stored capacity numbers.

desktop-sidecar/build.gradle.kts

@@ -0,0 +1,46 @@
+plugins {
+    kotlin("multiplatform") version "2.3.20"
+    kotlin("plugin.compose") version "2.3.20"
+    id("org.jetbrains.compose") version "1.10.3"
+}
+
+repositories {
+    mavenCentral()
+    google()
+}
+
+kotlin {
+    jvm("desktop")
+    jvmToolchain(21)
+
+    sourceSets {
+        val desktopMain by getting {
+            dependencies {
+                implementation(compose.desktop.currentOs)
+                implementation(compose.foundation)
+                implementation(compose.material3)
+                implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
+                implementation("org.xerial:sqlite-jdbc:3.53.0.0")
+            }
+        }
+
+        val desktopTest by getting {
+            dependencies {
+                implementation(kotlin("test"))
+            }
+        }
+    }
+}
+
+compose.desktop {
+    application {
+        mainClass = "com.block.agenttaskqueue.sidecar.MainKt"
+
+        nativeDistributions {
+            targetFormats(org.jetbrains.compose.desktop.application.dsl.TargetFormat.Dmg)
+            packageName = "AgentTaskQueueSidecar"
+            packageVersion = "1.0.0"
+            description = "Desktop sidecar for visualizing agent-task-queue state"
+        }
+    }
+}

desktop-sidecar/settings.gradle.kts

@@ -0,0 +1 @@
+rootProject.name = "agent-task-queue-sidecar"