---
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.
