Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,10 @@ Screenshots show whatever was on screen, so look over a hand-off before sharing

## Get started

On first launch, choose **Check Access**, follow macOS's Screen Recording permission prompts, and relaunch if macOS asks.

> **Screen Recording enabled but capture still denied:** follow the [step-by-step Screen Recording recovery guide](docs/troubleshooting.md#screen-recording-enabled-but-capture-still-fails).

1. Open the app you’re working on, such as a local dev server in your browser.
2. In ContextLens, press <kbd>⌘</kbd><kbd>N</kbd>, choose that window under **Which window?**, and click **Start Capture**.
3. Use your app as usual: open the menu, reproduce the bug, walk through the flow. Click **Stop Capture** when you’re done.
Expand Down
36 changes: 34 additions & 2 deletions docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,41 @@ macOS blocks the first launch of these unnotarized builds. If you trust the down

## Permissions and capture

Grant Screen Recording in System Settings → Privacy & Security → Screen & System Audio Recording (named Screen Recording on older macOS). Approve the installed copy and relaunch when macOS asks. Optional Accessibility permission enables clicked-control labels; capture works without those labels. ContextLens does not request typed text, password values or audio.
### First-time Screen Recording setup

If Settings shows access enabled but no windows appear, confirm which app path is running and use **Check Access**. A changed development signature or a transition to Developer ID distribution can require fresh consent. Follow [permissions](permissions.md) for targeted manual recovery. No permission database is reset by a build or installation.
First-time users normally follow the standard macOS permission grant flow:

1. Open your installed copy of ContextLens, normally `/Applications/ContextLens.app`.
2. In ContextLens's Capture panel, choose **Check Access** and respond to the macOS permission prompt.
3. Open **System Settings → Privacy & Security → Screen & System Audio Recording** (called **Screen Recording** on older macOS). Enable ContextLens in the **upper Screen & System Audio Recording list**. If it is missing, use **+ beneath that list** to add your installed app.
4. Follow any macOS **Quit & Reopen** request. Reopen the same installed copy and choose **Check Access** again, then select a window to capture.

On macOS 26, the separate lower **System Audio Recording Only** list grants audio-only access. Enabling ContextLens there does not authorize window capture. Use the upper list for Screen Recording, even though ContextLens itself does not record audio. Optional Accessibility permission enables clicked-control labels; capture works without those labels, and ContextLens does not read typed text or password values.

Normally, first-time setup ends after the standard grant and relaunch. Use the recovery procedure below only if access remains denied despite an enabled entry.

### Screen Recording enabled but capture still fails

This procedure successfully restored access in an observed macOS 26 case where ScreenCaptureKit returned permission denial **`-3801`** even though ContextLens was enabled in Settings.

An ad-hoc-signed app update can change the identity that macOS previously approved, leaving an enabled entry that no longer authorizes the updated app. **This can happen even with only one ContextLens installation.** Multiple copies can make identifying the approved app harder, but are not required for this failure. The [technical permission and signing explanation](permissions.md#signing-and-upgrades) describes why.

Reconnect the installed app manually:

1. **Save your work and quit ContextLens fully** with **ContextLens → Quit ContextLens** or <kbd>⌘</kbd><kbd>Q</kbd>. Closing its window alone does not quit the app. If other ContextLens copies are open, quit those too.
2. Open **System Settings → Privacy & Security → Screen & System Audio Recording**.
3. In the **upper Screen & System Audio Recording list**, select **ContextLens** and click **−** to remove its entry. If ContextLens is absent from that list, continue to step 4. Remove **only ContextLens**; leave other apps and the separate **System Audio Recording Only** list unchanged.
4. Click **+ beneath the upper list**. In the file chooser, press <kbd>⌘</kbd><kbd>⇧</kbd><kbd>G</kbd>, enter `/Applications`, and press Return. Select **ContextLens.app** and click **Open** to add `/Applications/ContextLens.app` again.
5. Confirm ContextLens is back in the **upper list** and turn its switch **on**.
6. Follow any macOS **Quit & Reopen** request. Otherwise, reopen `/Applications/ContextLens.app` from Finder. Use that same installed copy throughout the procedure.
7. Open ContextLens's Capture panel and choose **Check Access**. Access should be verified through ScreenCaptureKit. If the window list is empty after verification, open an application window and refresh.
8. Select a test window and start a short capture. Make a visible change, then stop and confirm a state appears in **Review**.

The expected result is verified access and a working window capture; the Settings switch alone is not proof. Other API errors can have different causes.

If access still fails, confirm the running app's path. Recent builds show **Running copy**, **Copy and signing details**, and **Show This Copy in Finder** beside the error. Note the app version/build, macOS version and exact error for a [bug report](https://github.com/Brendan-Lim/ContextLens/issues), keeping private logs and screen content local. See [permission diagnostics](permissions.md#interpret-the-apps-result) for the meanings of unverified, denied and failed checks. This procedure changes only ContextLens's permission entry; keep macOS security protections enabled.

### Other capture issues

If the selected window closes or becomes unavailable, start a new capture and explicitly choose a target. The recorder must not substitute a different window or the whole display.

Expand Down
Loading