Peekaboo MCP

--- summary: "Working log for AXorcist boundary follow-ups (Nov 19, 2025)." read_when: - "tracking AXorcist/Peekaboo accessibility refactor progress" - "assigning next tasks for AX toolkit/Peekaboo separation" --- # AXorcist Refactor Work List — Nov 19, 2025 _Status: Archived · Focus: AXorcist/Peekaboo boundary follow-ups._ ## ✅ Done recently - InputDriver now powers all click/drag/scroll/hotkey usage from Peekaboo; direct CGEvents removed. - SwiftLint rule warns on AXUIElement/CGEvent in Peekaboo UI services. - WindowIdentityUtilities delegates to AXWindowResolver; MouseLocationUtilities delegates to AppLocator. - CaptureOutput/SCS stream path has bounded timeout + DEBUG hooks; CLI tests pass. - Screen capture fallback logs engine + duration; env/flag control (`--capture-engine`, `PEEKABOO_CAPTURE_ENGINE`, `PEEKABOO_DISABLE_CGWINDOWLIST`). - Timeout helper (`AXTimeoutHelper`) moved into AXorcist; shared with Peekaboo. - AXorcist tests now cover InputDriver, AppLocator, AXWindowResolver, and timeout behavior. - Tool filtering allow/deny now documented + tested (PeekabooAgentRuntime + docs). - CLI command helpers (`CommandHelpers`, `DragCommand`, `AppCommand`) now go through `AXApp`/`AXWindowHandle`; no raw AXUIElement usage in PeekabooCore or the main CLI entry points. - SwiftLint `no_direct_ax_in_peekaboo` rule now errors instead of warning (enforced across PeekabooCore). - UIAutomationService/DialogService/WindowIdentity helpers + tests now consume `AXApp`/`AXWindowHandle`; no AXUIElement references left in PeekabooCore. - Inspector/TestHost permission UIs now use `AXPermissionHelpers`; no direct `AXIsProcessTrusted` outside AXorcist helpers. - Screen capture legacy CG fallback is gated (`PEEKABOO_ALLOW_LEGACY_CAPTURE`) and macOS 14+ builds stay on ScreenCaptureKit, removing the deprecated API warning. ## 🎯 Remaining tasks 1. **AX facade adoption** (follow-up) - Add coverage for the new permission wrappers (Inspector/TestHost UI tests or snapshots) so regressions are caught without manual inspection. - Audit any remaining app targets (e.g., mac app overlays) for latent AX APIs and migrate them before the lint becomes repo-wide. 2. **CG fallback tightening** (partial) - Now controlled via flag/env; still need an opt-in observer or telemetry for CLI output if desired. - Once scrub completes, flip SwiftLint custom rule from warning → error. 3. **AXorcist observability hook** (done via fallback runner logging) — no further API work planned; logging covers current needs. 4. **Documentation cleanup** - Update README/docs to mention capture-engine flag/env (done in README/config docs) and new security guidance (tools allow/deny). Keep doc parity in future releases. 5. **Future nice-to-haves** - Evaluate removing `CGWindowListCreateImage` entirely once SC reliability is proven. - Consider public API surface for peekaboo-specific heuristics (e.g., `AXWindowScore` objects) if we need cross-tool reuse. ## Tracking - Owner: Peekaboo core team (AX boundary). - Repo: Peekaboo + AXorcist (submodule). - Next update checkpoint: after lint is tightened and remaining AXUIElement references are gone.