feat: progressive skeleton traversal with ref-rooted drill-down

.githooks/pre-commit

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Pre-commit hook for agent-desktop.
+# Mirrors the CI quality gates so a failing commit never reaches origin.
+#
+# Setup (once per clone):
+#   git config core.hooksPath .githooks
+#
+# Bypass for a single commit (only when truly necessary):
+#   git commit --no-verify
+
+set -euo pipefail
+
+if [ -n "${SKIP_PRECOMMIT:-}" ]; then
+    echo "pre-commit: SKIP_PRECOMMIT set, skipping"
+    exit 0
+fi
+
+if ! command -v cargo >/dev/null 2>&1; then
+    echo "pre-commit: cargo not found in PATH, skipping (install Rust to enable)"
+    exit 0
+fi
+
+cd "$(git rev-parse --show-toplevel)"
+
+if git diff --cached --name-only --diff-filter=ACMR | grep -qE '\.(rs|toml)$'; then
+    HAS_RUST_CHANGES=1
+else
+    HAS_RUST_CHANGES=0
+fi
+
+if [ "$HAS_RUST_CHANGES" -eq 0 ]; then
+    echo "pre-commit: no Rust changes staged, skipping cargo checks"
+    exit 0
+fi
+
+run() {
+    local label="$1"
+    shift
+    printf '\033[1;34m▶ %s\033[0m\n' "$label"
+    if ! "$@"; then
+        printf '\033[1;31m✗ %s failed\033[0m\n' "$label" >&2
+        echo "" >&2
+        echo "pre-commit: refusing the commit. Fix the issues above or rerun with SKIP_PRECOMMIT=1 to bypass." >&2
+        exit 1
+    fi
+}
+
+run "cargo fmt --all -- --check" cargo fmt --all -- --check
+run "cargo clippy --all-targets -- -D warnings" cargo clippy --all-targets -- -D warnings
+run "cargo test --lib --workspace" cargo test --lib --workspace
+
+printf '\033[1;32m✓ pre-commit checks passed\033[0m\n'

.gitignore

@@ -73,5 +73,8 @@ docs/*
 !docs/architecture.excalidraw
 !docs/architecture.png
 !docs/phases.md
+!docs/solutions/
+!docs/solutions/**
 todos/
-.cursor/
+.cursor/
+.context/

CLAUDE.md

@@ -19,6 +19,16 @@ cargo tree -p agent-desktop-core               # Verify no platform crate leaks
 
 Run the binary: `./target/release/agent-desktop snapshot --app Finder -i`
 
+## Pre-commit Hook
+
+The repo ships a pre-commit hook at `.githooks/pre-commit` that runs `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, and `cargo test --lib --workspace` against staged Rust changes. Wire it up once after cloning:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+Bypass for an emergency commit with `git commit --no-verify` or `SKIP_PRECOMMIT=1 git commit ...`.
+
 ## Project Overview
 
 Cross-platform Rust CLI + MCP server enabling AI agents to observe and control desktop applications via native OS accessibility trees.
@@ -57,6 +67,10 @@ agent-desktop/
 ├── clippy.toml             # project-wide lint config
 ├── crates/
 │   ├── core/               # agent-desktop-core (platform-agnostic)
+│   │   └── src/
+│   │       ├── ref_alloc.rs      # Shared ref helpers (INTERACTIVE_ROLES, is_collapsible)
+│   │       ├── snapshot_ref.rs   # Ref-rooted drill-down (run_from_ref)
+│   │       └── commands/         # one file per command
 │   ├── macos/              # agent-desktop-macos (Phase 1)
 │   ├── windows/            # agent-desktop-windows (stub → Phase 2)
 │   └── linux/              # agent-desktop-linux (stub → Phase 2)
@@ -66,6 +80,8 @@ agent-desktop/
 │   ├── cli_args.rs         # all command argument structs
 │   ├── dispatch.rs         # command dispatcher + parse helpers
 │   └── batch_dispatch.rs   # batch command execution
+├── docs/
+│   └── solutions/          # documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (module, tags, problem_type); relevant when implementing or debugging in documented areas
 └── tests/
     ├── fixtures/           # golden JSON snapshots
     └── integration/        # macOS CI integration tests
@@ -284,16 +300,20 @@ Error responses:
 - RefMap stored at `~/.agent-desktop/last_refmap.json` with `0o600` permissions, directory at `0o700`
 - Each snapshot REPLACES the refmap file entirely (atomic write via temp + rename)
 - Action commands use optimistic re-identification: `(pid, role, name, bounds_hash)`. Return `STALE_REF` on mismatch.
+- Progressive traversal: `--skeleton` clamps depth to 3, annotates truncated containers with `children_count`. Named/described containers at boundary receive refs as drill-down targets
+- Drill-down: `--root @ref` starts from a previously-discovered ref with scoped invalidation (only that ref's subtree refs are replaced on re-drill)
+- RefMap size check: write-side guard prevents >1MB refmap files
 
 ## PlatformAdapter Trait
 
-12 methods with default implementations returning `not_supported()`:
+13 methods with default implementations returning `not_supported()`:
 
 ```rust
 pub trait PlatformAdapter: Send + Sync {
     fn list_windows(&self, filter: &WindowFilter) -> Result<Vec<WindowInfo>, AdapterError>;
     fn list_apps(&self) -> Result<Vec<AppInfo>, AdapterError>;
     fn get_tree(&self, win: &WindowInfo, opts: &TreeOptions) -> Result<AccessibilityNode, AdapterError>;
+    fn get_subtree(&self, handle: &NativeHandle, opts: &TreeOptions) -> Result<AccessibilityNode, AdapterError>;
     fn execute_action(&self, handle: &NativeHandle, action: Action) -> Result<ActionResult, AdapterError>;
     fn resolve_element(&self, entry: &RefEntry) -> Result<NativeHandle, AdapterError>;
     fn check_permissions(&self) -> PermissionStatus;
@@ -406,7 +426,9 @@ Target binary size: <15MB per platform.
 - `cargo test --workspace`
 - Binary size check: fail if release binary exceeds 15MB
 
-## Implemented Commands (50)
+## Implemented Commands (53)
+
+> **Platform note:** All 53 commands are implemented on macOS (Phase 1). Windows and Linux adapters are planned (Phase 2/3) and will support the same command surface; notification commands depend on platform-specific notification APIs.
 
 | Category | Commands |
 |----------|----------|
@@ -415,9 +437,10 @@ Target binary size: <15MB per platform.
 | Interaction (14) | `click`, `double-click`, `triple-click`, `right-click`, `type`, `set-value`, `clear`, `focus`, `select`, `toggle`, `check`, `uncheck`, `expand`, `collapse` |
 | Scroll (2) | `scroll`, `scroll-to` |
 | Keyboard (3) | `press`, `key-down`, `key-up` |
-| Mouse (5) | `hover`, `drag`, `mouse-move`, `mouse-click`, `mouse-down`, `mouse-up` |
+| Mouse (6) | `hover`, `drag`, `mouse-move`, `mouse-click`, `mouse-down`, `mouse-up` |
+| Notifications (4) *(macOS)* | `list-notifications`, `dismiss-notification`, `dismiss-all-notifications`, `notification-action` |
 | Clipboard (3) | `clipboard-get`, `clipboard-set`, `clipboard-clear` |
-| Wait (1) | `wait` (with `--element`, `--window`, `--text`, `--menu` flags) |
+| Wait (1) | `wait` (with `--element`, `--window`, `--text`, `--menu`, `--notification` flags) |
 | System (3) | `status`, `permissions`, `version` |
 | Batch (1) | `batch` |
 

README.md

@@ -11,7 +11,8 @@
 ## Key Features
 
 - **Native Rust CLI**: Fast, single binary, no runtime dependencies
-- **50 commands**: Observation, interaction, keyboard, mouse, clipboard, window management
+- **53 commands**: Observation, interaction, keyboard, mouse, notifications, clipboard, window management
+- **Progressive skeleton traversal**: 78–96% token reduction on dense apps via shallow overview + targeted drill-down
 - **Snapshot & refs**: AI-optimized workflow using deterministic element references (`@e1`, `@e2`)
 - **AX-first interactions**: Every action exhausts pure accessibility API strategies before falling back to mouse events
 - **Structured JSON output**: Machine-readable responses with error codes and recovery hints
@@ -52,6 +53,24 @@ agent-desktop permissions --request   # trigger system dialog
 
 ## Core Workflow for AI
 
+For dense apps (Slack, VS Code, Notion), use **progressive skeleton traversal** to minimize token usage:
+
+```bash
+# 1. Shallow overview — depth-3 map, truncated containers show children_count
+agent-desktop snapshot --skeleton --app Slack -i --compact
+
+# 2. Drill into a region of interest (named containers get refs as drill targets)
+agent-desktop snapshot --root @e3 -i --compact
+
+# 3. Act on an element found in the drill-down
+agent-desktop click @e12
+
+# 4. Re-drill the same region to verify the state change
+agent-desktop snapshot --root @e3 -i --compact
+```
+
+For simple apps, a full snapshot is fine:
+
 ```bash
 agent-desktop snapshot --app Finder -i   # get interactive elements with refs
 agent-desktop click @e3                  # click a button by ref
@@ -60,8 +79,6 @@ agent-desktop press cmd+s               # keyboard shortcut
 agent-desktop snapshot -i               # re-observe after UI changes
 ```
 
-The snapshot + ref pattern is optimal for LLMs: refs provide deterministic element selection without re-querying the accessibility tree.
-
 ```
 Agent loop:  snapshot → decide → act → snapshot → decide → act → ...
 ```
@@ -141,6 +158,18 @@ agent-desktop maximize w-4521            # maximize
 agent-desktop restore w-4521             # restore
 ```
 
+### Notifications *(macOS only)*
+
+```bash
+agent-desktop list-notifications                       # list all notifications
+agent-desktop list-notifications --app "Slack"         # filter by app
+agent-desktop list-notifications --text "deploy" --limit 5  # filter by text
+agent-desktop dismiss-notification 1                   # dismiss by index
+agent-desktop dismiss-all-notifications                # dismiss all
+agent-desktop dismiss-all-notifications --app "Slack"  # dismiss all from app
+agent-desktop notification-action 1 --action "Reply"   # click action button
+```
+
 ### Clipboard
 
 ```bash
@@ -192,6 +221,8 @@ agent-desktop snapshot [OPTIONS]
 | `--compact` | off | Omit empty structural nodes |
 | `--include-bounds` | off | Include pixel bounds (x, y, width, height) |
 | `--max-depth <N>` | 10 | Maximum tree depth |
+| `--skeleton` | off | Shallow 3-level overview; truncated containers show `children_count` and get refs as drill targets |
+| `--root <REF>` | - | Start traversal from this ref; merges into existing refmap with scoped invalidation |
 | `--surface <TYPE>` | window | `window`, `focused`, `menu`, `menubar`, `sheet`, `popover`, `alert` |
 
 ## JSON Output
@@ -262,6 +293,7 @@ snapshot → act → STALE_REF? → snapshot again → retry
 | Screenshot | **Yes** | Planned | Planned |
 | Clipboard | **Yes** | Planned | Planned |
 | App & window management | **Yes** | Planned | Planned |
+| Notifications | **Yes** | Planned | Planned |
 
 ## Development
 

crates/core/src/adapter.rs

@@ -30,6 +30,7 @@ pub struct TreeOptions {
     pub interactive_only: bool,
     pub compact: bool,
     pub surface: SnapshotSurface,
+    pub skeleton: bool,
 }
 
 impl Default for TreeOptions {
@@ -40,6 +41,7 @@ impl Default for TreeOptions {
             interactive_only: false,
             compact: false,
             surface: SnapshotSurface::Window,
+            skeleton: false,
         }
     }
 }
@@ -244,4 +246,12 @@ pub trait PlatformAdapter: Send + Sync {
     ) -> Result<ActionResult, AdapterError> {
         Err(AdapterError::not_supported("notification_action"))
     }
+
+    fn get_subtree(
+        &self,
+        _handle: &NativeHandle,
+        _opts: &TreeOptions,
+    ) -> Result<AccessibilityNode, AdapterError> {
+        Err(AdapterError::not_supported("get_subtree"))
+    }
 }