Omahub
← All plugins
S

Scope

by sanjyay

Select anything on screen and get a web-grounded explanation or solution with Codex.

GitHub

Security review

Review recommended · 2 findings

Deterministic scan — not a security guarantee

Low
Risk level
Low
Analyzed commit
9b6f2d6
Scanned
1 month ago

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
9b6f2d6
Reviewed
1 month ago

The plugin is a screen-selection overlay that captures only the user-selected region and sends it to Codex for analysis. The code shows careful security practices: structured argument passing, path validation, bubblewrap sandboxing, and fail-closed behavior. The deterministic scan's low findings are in the test suite and are just binary PNG test data, not obfuscated executable code.

  • The plugin transmits selected screen content to OpenAI/Codex, which is inherent to its purpose and disclosed in the README.
  • The 'Open Agent' escalation launches a normal interactive Codex session with full user permissions, but this is an explicit user action and clearly documented.
  • The full scope-helper script was not fully sampled; the human moderator should spot-check the remaining portions of scripts/scope-helper and the codex adapter before publishing.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/sanjyay/scope --enable
Productivity #bar #quickshell #ai

Scope

Circle anything on your screen and let Codex explain, research, or solve it.

Scope is a visual context tool for Omarchy. Select anything on your screen and get a web-grounded explanation, solution, or research result from Codex—then hand that context directly to the agent when you need to go deeper.

https://github.com/user-attachments/assets/fd73f463-649e-4ec4-8cb1-6dff40312f38

see something
    → select it
    → get an answer

The interaction is inspired by the convenience of Circle-to-Search, but Scope is built as a native Omarchy workflow around the desktop, Quickshell, and your configured Codex agent.

Why Scope

Without Scope, visual research often means:

see something
    → screenshot
    → save or copy
    → open a browser or AI tool
    → upload
    → explain what to inspect
    → search

With Scope, the workflow is simply:

see something
    → select it
    → get an answer

Scope is useful when the thing you need to understand is visible, but not easily selectable or worth turning into a separate screenshot file.

What it does

  1. Open Scope from the Omarchy bar or the optional keyboard shortcut.
  2. Draw a freehand lasso around the screen region you want to inspect.
  3. Scope captures only that region and masks the rest.
  4. Protected Codex Search analyzes the image and searches the web when useful.
  5. Scope shows a concise answer and sources inline.
  6. Ask a follow-up using the same selected image, or choose Open Agent for an interactive Codex session with the visual context.

Architecture

Scope operates as a Wayland-native, sandboxed overlay.

Protective Boundaries

  1. Restricted filesystem: Protected Search runs the entire Codex process in a minimal bubblewrap filesystem containing system runtime files and the current Scope session only. Arbitrary home, project, and host /tmp files are not visible.
  2. Minimal tools: Protected Search keeps supplied-image input and web search while disabling model-controlled shell and path-based image tools.
  3. Fail closed: Scope requires keyring-backed ChatGPT authentication and aborts if the protected filesystem or authentication channel cannot be established.
  4. Explicit escalation: Open Agent launches the user's normal interactive Codex session with normal permissions.

Use cases

Errors and debugging

Circle a terminal error, stack trace, package/build failure, Python traceback, QML error, browser error, GUI warning, or configuration problem. Scope can explain what is visible and find relevant documentation or sources.

Scope is not an application crash or coredump replacement; Omarchy already has native tooling for that. Its advantage is working on anything visible, even when no crash report exists.

Visual UI and context

Select an unfamiliar icon, setting, control, or software interface to get an explanation of what it is and how it is typically used.

Charts and diagrams

Use a selection to ask about a chart, diagram, technical visual, or other information that is difficult to describe precisely in text.

Hard-to-copy content

Scope works with screenshots, video frames, remote desktops, images, and non-selectable UI.

Research

Select a product, object, or visual reference and get current web-grounded information with sources when the search path finds them.

Deeper work

Scope result
    → Open Agent
    → interactive Codex with the selected context

Scope does not claim to identify real people from faces.

Installation

Scope is installed as a native Omarchy plugin:

omarchy plugin add https://github.com/sanjyay/scope --enable

Scope installs normally through omarchy plugin add; authentication is not an installation step. Before Protected Search can run, Codex must use your OS keyring for ChatGPT authentication:

codex -c 'cli_auth_credentials_store="keyring"' login --device-auth

This is your existing ChatGPT Codex login, not API-key billing. Scope never stores your credentials. Protected Search performs a bounded local readiness check each time Scope opens and shows setup guidance if Codex, bubblewrap, Secret Service, or keyring-backed login is unavailable.

Enabling the plugin adds a Scope action to the Omarchy bar's default right section. Click it to open Scope. Scope does not edit ~/.config/hypr/bindings.lua.

To remove the plugin:

omarchy plugin remove scope

Usage

<img width="280" height="102" alt="image" src="https://github.com/user-attachments/assets/cab98835-5fe8-4d1d-a6fd-06c174c43938" />
  1. Click the Scope icon in the Omarchy bar.
  2. Draw around something on screen and release.
  3. Read the answer and open sources explicitly when you want to inspect them.
  4. Type a follow-up question if you want another search on the same selection.
  5. Choose Expand for the full result or Open Agent for interactive Codex work.
  6. Press Escape to cancel an active search or close Scope.

The overlay is reusable immediately after cancellation or an Open Agent handoff.

Optional keyboard shortcut

The bar widget is the default access path. If you prefer keyboard access, add this optional entry to ~/.config/hypr/bindings.lua:

o.bind("SUPER + SHIFT + Q", "Scope", "omarchy-shell shell summon scope '{}'")

This is a manual user preference; Scope does not add or remove the binding. If you added it yourself, remove the line when you no longer want the shortcut.

Features

  • Native Omarchy overlay and bar-widget plugin kinds.
  • Freehand lasso with selected-region-only capture and polygon masking.
  • Codex vision analysis and protected web search.
  • Concise plain-text answers with structured clickable sources.
  • Validated source URLs that open safely in the browser.
  • Expandable results and follow-up questions using the same selected image.
  • Explicit Open Agent handoff to interactive Codex.
  • Immediate Escape cancellation and reusable session lifecycle.
  • Omarchy Color/Style theme integration.
  • Private runtime storage with restrictive permissions and automatic cleanup.
  • Fail-closed behavior when the selected Omarchy agent is not Codex.

Agent compatibility

Scope currently supports Codex only. Protected Scope Search requires:

  • Codex CLI installed
  • Codex authenticated with ChatGPT through the OS keyring
  • bubblewrap and the user's Secret Service session available
  • Codex set as the current default Omarchy agent

Other Omarchy agents may be added after their complete image + web-search + protected-execution path is verified.

Privacy & security

  • Scope does not continuously watch the screen or take background screenshots.
  • Capture begins only after an explicit selection, and only the selected region is retained.
  • Temporary images and handoff context stay in private runtime storage with restrictive permissions and bounded cleanup. Scope keeps no screenshot history.
  • Scope does not use the clipboard for Search and does not store API keys or tokens. It uses the user's existing Codex authentication.
  • Selected images, questions, and web-search data may be transmitted through Codex/OpenAI according to the user's service and configuration terms.
  • Screenshot contents, model answers, and web results are untrusted data.
  • Protected Search is restricted/read-only. Sources open only after an explicit click; the browser is not opened automatically.
  • Open Agent is an explicit escalation into normal interactive Codex.

See SECURITY.md for the detailed threat model.

Limitations

  • Codex is the only supported protected visual-search backend in this release.
  • Scope inherits Codex and model/provider safety restrictions; some visual questions may be refused.
  • Scope is not intended for facial recognition or identifying real people from faces.
  • AI answers and web results can be wrong, incomplete, or outdated. Check the sources for important decisions.
  • Web search requires internet access and a working Codex account/service.
  • Response time depends on the model, network, provider load, and search.
  • Some responses may not include useful web sources.

Technical overview

Scope is a native Omarchy Quattro multi-kind plugin with an overlay and a bar-widget entry point:

Omarchy bar / optional shortcut
        ↓
Scope overlay
        ↓
freehand lasso
        ↓
selected Wayland region
        ↓
private masked image
        ↓
protected Codex search
        ↓
answer + sources
        ↓
ResultCard
        ↓
optional Open Agent handoff

The bar launcher is a native BarWidget/BarIconButton using the custom Scope icon and in-process shell summon path. It launches the existing overlay; it does not create a second Scope instance or spawn a separate daemon.

Useful entry points and implementation areas:

Development

The repository includes the plugin manifest, runtime helper, QML components, security documentation, and regression tests. Validate changes in an Omarchy environment with the current plugin validator, qmllint, and the test runner.

Please include the Omarchy version, Scope commit, Codex CLI version, reproduction steps, and sanitized logs in bug reports. Never include credentials.

License

Scope is released under the MIT License.