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 .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Language stats: count the Swift app, not its release tooling, benchmarks or experiments.
scripts/** linguist-detectable=false
Benchmarks/** linguist-detectable=false
Experiments/** linguist-detectable=false
46 changes: 18 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,14 @@ Capture the window you’re building, mark what should change, and hand the resu

<br>

[**Download for macOS**](https://github.com/Brendan-Lim/ContextLens/releases/tag/v0.3.0-preview.1) &nbsp;·&nbsp; [**Install with Homebrew**](#install) &nbsp;·&nbsp; [**Get started**](#get-started)
[**Download for macOS**](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.0-preview.1) &nbsp;·&nbsp; [**Install with Homebrew**](#install) &nbsp;·&nbsp; [**Get started**](#get-started)

<p>
<a href="Package.swift"><img src="https://img.shields.io/badge/Swift-native-F05138?style=flat&amp;logo=swift&amp;logoColor=white" alt="Native Swift app"></a>
<a href="docs/building.md"><img src="https://img.shields.io/badge/macOS-14%2B-555555?style=flat&amp;logo=apple&amp;logoColor=white" alt="Minimum deployment target: macOS 14 or later"></a>
<a href="docs/building.md"><img src="https://img.shields.io/badge/Apple_Silicon-arm64-55677D?style=flat&amp;logo=apple&amp;logoColor=white" alt="Apple Silicon arm64"></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/Brendan-Lim/ContextLens?style=flat&amp;color=2ea44f" alt="MIT license"></a>
<a href=".github/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Brendan-Lim/ContextLens/ci.yml?branch=main&amp;event=push&amp;style=flat&amp;label=CI&amp;logo=githubactions&amp;logoColor=white" alt="GitHub Actions CI status on main"></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/bstack-tools/ContextLens?style=flat&amp;color=2ea44f" alt="MIT license"></a>
<a href=".github/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/bstack-tools/ContextLens/ci.yml?branch=main&amp;event=push&amp;style=flat&amp;label=CI&amp;logo=githubactions&amp;logoColor=white" alt="GitHub Actions CI status on main"></a>
</p>

<sub>Free and open source &nbsp;·&nbsp; Apple Silicon &nbsp;·&nbsp; macOS 14 Sonoma or later</sub>
Expand Down Expand Up @@ -76,7 +76,7 @@ You spot it straight away: the button that’s a few pixels off, the avatar that

<br>

## Why developers use ContextLens
## Why use ContextLens

<table>
<tr>
Expand Down Expand Up @@ -153,18 +153,9 @@ ContextLens prepares the context. Your agent makes the change in your codebase,

### Download

**[Download ContextLens for macOS](https://github.com/Brendan-Lim/ContextLens/releases/tag/v0.3.0-preview.1)**. Unzip it, move **ContextLens** into your Applications folder, and open it from there.
**[Download ContextLens for macOS](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.0-preview.1)**. Unzip it, move **ContextLens** into your Applications folder, and open it from there.

ContextLens is in public preview. The first stable release, v0.3.1, will add a drag-to-install disk image.

<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/media/screens/E-dmg-dark.png">
<img src="docs/media/screens/E-dmg-light.png" width="720" alt="The ContextLens Mac installer: drag ContextLens into Applications.">
</picture>
<br>
<sub>Drag ContextLens into Applications. · v0.3.1</sub>
</p>
ContextLens is in public preview.

### Homebrew

Expand All @@ -180,7 +171,7 @@ ContextLens is free and open source, and it isn’t notarized by Apple yet, so m
2. Open **System Settings → Privacy & Security**, scroll down, click **Open Anyway**, and confirm.
3. When prompted, allow **Screen Recording** for ContextLens, then reopen the app.

Only do this for a copy downloaded from this repository’s [Releases](https://github.com/Brendan-Lim/ContextLens/releases) page; each release lists its SHA-256 checksum. Apple explains the steps in [Safely open apps on your Mac](https://support.apple.com/en-us/102445). You can optionally allow **Accessibility**, which lets ContextLens name the controls you click in a capture. It never reads what you type. More help: [Permissions](docs/permissions.md) · [Troubleshooting](docs/troubleshooting.md)
Only do this for a copy from this repository’s [Releases](https://github.com/bstack-tools/ContextLens/releases) page, which lists each release’s SHA-256 checksum. Optionally allow **Accessibility** so ContextLens can name the controls you click; it never reads what you type. If capture is still denied, see the [Screen Recording recovery guide](docs/troubleshooting.md#screen-recording-enabled-but-capture-still-fails). More help: [Permissions](docs/permissions.md) · [Troubleshooting](docs/troubleshooting.md)

<br>

Expand All @@ -197,16 +188,13 @@ 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.
4. In **Review**, untick the states you don’t need and click the one that shows the problem.
5. In **Mark Up**, drag over the problem and write what should change. Add as many marks as you like.
6. In **Hand Off**, click **Save Hand Off**, then **Copy prompt**, and paste it into your coding agent.
1. On first launch, choose **Check Access** and follow macOS's Screen Recording prompts.
2. Open the app you’re working on, such as a local dev server in your browser.
3. In ContextLens, press <kbd>⌘</kbd><kbd>N</kbd>, choose that window under **Which window?**, and click **Start Capture**.
4. Use your app as usual: open the menu, reproduce the bug, walk through the flow. Click **Stop Capture** when you’re done.
5. In **Review**, untick the states you don’t need and click the one that shows the problem.
6. In **Mark Up**, drag over the problem and write what should change. Add as many marks as you like.
7. In **Hand Off**, click **Save Hand Off**, then **Copy prompt**, and paste it into your coding agent.

Tip: **High** sensitivity (the default) catches small interface changes. **Low** ignores minor ones and keeps fewer states.

Expand All @@ -217,20 +205,22 @@ Tip: **High** sensitivity (the default) catches small interface changes. **Low**
ContextLens is **[MIT licensed](LICENSE)**, including its branding. It’s written in Swift with zero third-party runtime dependencies, and comes with a command-line tool that uses the same export logic as the app.

```sh
git clone https://github.com/Brendan-Lim/ContextLens.git
git clone https://github.com/bstack-tools/ContextLens.git
cd ContextLens
scripts/build-app.sh # builds dist/ContextLens.app and dist/contextlens-cli
scripts/verify.sh # runs the test suite
```

[Building](docs/building.md) · [Testing](docs/native-testing.md) · [Research](docs/research.md) · [Architecture](docs/architecture.md) · [Export format](docs/export-format.md) · [Using with Claude Code](Integrations/claude-code.md) · [Releases and testing](docs/official-release-preparation.md)

Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) first, and [open an issue](https://github.com/Brendan-Lim/ContextLens/issues) for bugs you can reproduce.
Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) first, and [open an issue](https://github.com/bstack-tools/ContextLens/issues) for bugs you can reproduce.

<br>

<div align="center">
<img src="Brand/mascot-peek.svg" width="72" alt="">
<br>
<sub>Stop explaining your UI. Just show it.</sub>
<br>
<sub>Built by <a href="https://github.com/Brendan-Lim">Brendan Lim</a> · part of <a href="https://github.com/bstack-tools">bstack</a></sub>
</div>
6 changes: 3 additions & 3 deletions distribution/homebrew/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Unnotarized preview channel

The separate `contextlens-preview` channel installs [ContextLens 0.3.0-preview.1](https://github.com/Brendan-Lim/ContextLens/releases/tag/v0.3.0-preview.1). The cask uses the verified published archive and actual SHA-256. [Candidate verification 42471268060](https://github.com/Brendan-Lim/homebrew-tap/actions/runs/42471268060) passed on a disposable arm64 macOS 15.8.2 runner with Homebrew 7.0.12: style, online audit, fetch/checksum, installation, app placement, CLI linking/help, quarantine retention, existing-app protection and uninstall preservation of session/export markers.
The separate `contextlens-preview` channel installs [ContextLens 0.3.0-preview.1](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.0-preview.1). The cask uses the verified published archive and actual SHA-256. [Candidate verification 42471268060](https://github.com/Brendan-Lim/homebrew-tap/actions/runs/42471268060) passed on a disposable arm64 macOS 15.8.2 runner with Homebrew 7.0.12: style, online audit, fetch/checksum, installation, app placement, CLI linking/help, quarantine retention, existing-app protection and uninstall preservation of session/export markers.

```sh
brew install --cask Brendan-Lim/tap/contextlens-preview
Expand All @@ -16,15 +16,15 @@ Previews are optimized arm64 builds for macOS 14+, ad-hoc signed without Develop

The cask installs `ContextLens.app` and links its embedded `contextlens-cli`. It conflicts with the future stable cask and default Homebrew installation refuses to overwrite an existing app. Quit and deliberately back up an existing copy before switching channels; do not use force/adopt options. Both channels share the bundle ID, sessions and CLI name, so do not treat another app directory as isolation.

Preview uninstall preserves sessions, settings and exported packages: there is no `zap` or deletion hook. Hosted checks use only a disposable GitHub macOS runner; manual Gatekeeper authorization, fresh-user Screen Recording and interactive capture/Hand Off remain pending. [Full preview instructions and report](https://github.com/Brendan-Lim/ContextLens/blob/main/docs/preview-releases.md).
Preview uninstall preserves sessions, settings and exported packages: there is no `zap` or deletion hook. Hosted checks use only a disposable GitHub macOS runner; manual Gatekeeper authorization, fresh-user Screen Recording and interactive capture/Hand Off remain pending. [Full preview instructions and report](https://github.com/bstack-tools/ContextLens/blob/main/docs/preview-releases.md).

Maintainers: `python3 scripts/validate.py` checks both channel templates and generated casks. Generate a preview cask with the main repository's `python3 scripts/preview-release.py update-tap VERSION /path/to/tap`. Push candidates under `preview/**` to run style, online audit, fetch and disposable install/uninstall checks before promoting to main. `scripts/test-preview-install.py` refuses to run outside a GitHub-hosted runner and does not authorize or launch the GUI app.

## Future signed/notarized stable channel

Stable ContextLens distribution is pending Developer ID signing and Apple notarization. This channel contains a cask template and validation tooling. **There is no installable stable `contextlens` cask yet.**

Source: [Brendan-Lim/ContextLens](https://github.com/Brendan-Lim/ContextLens). The native app captures and annotates a selected macOS window and exports local visual context for coding agents.
Source: [bstack-tools/ContextLens](https://github.com/bstack-tools/ContextLens). The native app captures and annotates a selected macOS window and exports local visual context for coding agents.

Validate the pending template with `python3 scripts/validate.py`. It uses Ruby's parser without inventing a checksum or download. The workflow audits a real cask only after a verified release exists.

Expand Down
2 changes: 1 addition & 1 deletion docs/beta-acceptance.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Record the test date, macOS version, architecture, Homebrew version, preview tag

## Installation and trust

1. Confirm the disposable machine has no ContextLens app/cask or `contextlens-cli` link and no sessions that matter. Review the official [preview release](https://github.com/Brendan-Lim/ContextLens/releases/tag/v0.3.0-preview.1) and [preview limitations](preview-releases.md). The ZIP SHA-256 must be `1cd84d6b15fc7aed7346ff1fd27382d5d2cd5a51637c7358861ddf55ebe0da45`.
1. Confirm the disposable machine has no ContextLens app/cask or `contextlens-cli` link and no sessions that matter. Review the official [preview release](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.0-preview.1) and [preview limitations](preview-releases.md). The ZIP SHA-256 must be `1cd84d6b15fc7aed7346ff1fd27382d5d2cd5a51637c7358861ddf55ebe0da45`.
2. Run `brew install --cask Brendan-Lim/tap/contextlens-preview`. Check `/Applications/ContextLens.app`, `command -v contextlens-cli`, and `xattr -p com.apple.quarantine /Applications/ContextLens.app`. This last command reads quarantine; it must not remove it. Verify the embedded `Contents/Resources/preview.json` records source `4b463d3e6dfc3ec4035f89d0e9f8787dee08ff4c` and unnotarized ad-hoc trust.
3. Open the app from Finder. Record the actual warning and available choices. No warning is not proof of Apple trust; note the machine's policy and prior authorization. A read-only assessment is `spctl --assess --type execute -vv /Applications/ContextLens.app`; the hosted runner returned rejection.
4. Only after the tester chooses to trust the verified origin, follow [Apple's Open Anyway procedure](https://support.apple.com/en-us/102445): try opening, dismiss the alert, open System Settings → Privacy & Security → Open Anyway, then confirm Open. Record the real result. Do not disable Gatekeeper, strip quarantine, use force/adopt flags, change managed policy or automate the approval.
Expand Down
2 changes: 1 addition & 1 deletion docs/building.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ For free binary downloads without Apple credentials, see the separate [unnotariz
Use an Apple Silicon Mac running macOS 14 or newer and Xcode with Swift 5.10 or newer. There are no production dependencies. Local verification used macOS 26.6.2, Xcode 26.6 and Swift 6.3.3. Hosted CI selects Xcode 26.3 on `macos-15` and records the actual versions. macOS 14 is the deployment target; execution on macOS 14 has not been verified.

```sh
git clone https://github.com/Brendan-Lim/ContextLens.git
git clone https://github.com/bstack-tools/ContextLens.git
cd ContextLens
scripts/build-app.sh
open dist/ContextLens.app
Expand Down
6 changes: 3 additions & 3 deletions docs/official-release-preparation.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Official unnotarized release preparation

The published download is [v0.3.0-preview.1](https://github.com/Brendan-Lim/ContextLens/releases/tag/v0.3.0-preview.1). v0.3.1/build 6 is an **unpublished candidate**, with ad-hoc signatures, no Developer ID and no Apple notarization. No installable stable Homebrew cask exists. The separate [Developer ID workflow](releasing.md) keeps its signing, notarization and Gatekeeper requirements.
The published download is [v0.3.0-preview.1](https://github.com/bstack-tools/ContextLens/releases/tag/v0.3.0-preview.1). v0.3.1/build 6 is an **unpublished candidate**, with ad-hoc signatures, no Developer ID and no Apple notarization. No installable stable Homebrew cask exists. The separate [Developer ID workflow](releasing.md) keeps its signing, notarization and Gatekeeper requirements.

## Candidate baseline

[Prepare-only run 42601149595](https://github.com/Brendan-Lim/ContextLens/actions/runs/42601149595) prepared the integrated Retina source below; its promotion job was skipped. Independent package verification and exact-byte native engineering checks passed all 14 engineering cases, including real Finder Light/Dark, drag/install/eject/launch, Low/High capture, Review/Mark Up, Hand Off and lifecycle/recovery. The seven owner-approved genuine Retina screenshots are integrated in the README; [the kit](screenshot-kit/README.md) describes their provenance.
[Prepare-only run 42601149595](https://github.com/bstack-tools/ContextLens/actions/runs/42601149595) prepared the integrated Retina source below; its promotion job was skipped. Independent package verification and exact-byte native engineering checks passed all 14 engineering cases, including real Finder Light/Dark, drag/install/eject/launch, Low/High capture, Review/Mark Up, Hand Off and lifecycle/recovery. The seven owner-approved genuine Retina screenshots are integrated in the README; [the kit](screenshot-kit/README.md) describes their provenance.

| Identity | Value |
|---|---|
Expand All @@ -27,7 +27,7 @@ Five human security cases remain pending: genuine quarantined first launch, user
3. Download that exact artifact into a fresh directory and verify it on an independent Mac:

```sh
gh run download RUN_ID --repo Brendan-Lim/ContextLens --name official-candidate-0.3.1 --dir CANDIDATE
gh run download RUN_ID --repo bstack-tools/ContextLens --name official-candidate-0.3.1 --dir CANDIDATE
(cd CANDIDATE && shasum -a 256 -c SHA256SUMS)
.build/dmg-python/bin/python scripts/unnotarized-release.py verify-assets CANDIDATE
```
Expand Down
Loading
Loading