Capture Engine Selection

Peekaboo supports two capture backends:

• modern: ScreenCaptureKit (SCStream/SCScreenshotManager)
• classic: CGWindowListCreateImage (legacy)

#How selection works

• Default: auto (classic/CoreGraphics first, then modern ScreenCaptureKit if allowed).
• Environment:
• PEEKABOO_CAPTURE_ENGINE=auto|modern|sckit|classic|cg (preferred)
• Back-compat: PEEKABOO_USE_MODERN_CAPTURE=true|false|modern-only|legacy
• CLI flags (set the env for this invocation):
• peekaboo capture live --capture-engine auto|modern|sckit|classic|cg
• peekaboo image --capture-engine ...
• peekaboo see --capture-engine ...

Aliases:

• modern: modern, sckit, sc, sck
• classic: classic, cg, legacy
• auto: auto

#Current policy (May 2026)

• Default: auto = try CGWindowList/CoreGraphics first, fallback to ScreenCaptureKit if CG fails.
• You can force SC-only via env PEEKABOO_DISABLE_CGWINDOWLIST=1.
• You can force classic/CG via --capture-engine classic|cg or PEEKABOO_CAPTURE_ENGINE=classic.

#Logging & telemetry

• ScreenCaptureService logs which engine was attempted and when fallback occurs.
• Consider adding env PEEKABOO_DISABLE_CGWINDOWLIST if you want to dogfood pure SC.

#When to use which

• Prefer auto for regular commands. Use modern for explicit ScreenCaptureKit regression checks.
• For reproducible capture failures, log the selected engine and fallback path before forcing an engine globally.