How lambchwrlie95/omarchy-circle-search works
1. Purpose and runtime model
- omarchy-circle-search is a small Rust/GTK4 Wayland utility, not a background daemon.
- It launches on demand, shows a full-screen overlay, lets the user draw a freehand selection, then either uploads the crop for reverse-image search or copies it for AI-chat use.
2. Top-level orchestration
- src/main.rs is the entrypoint and control plane.
- It handles CLI flags like --copy and --notify, performs dependency checks, loads config/theme, starts the overlay, and dispatches the result into the correct post-capture flow.
3. Overlay and input capture boundary
- src/overlay.rs owns the interactive UI.
- It uses GTK4 with gtk4-layer-shell to present a Wayland-native overlay above the desktop.
- This layer handles engine selection, mouse drag tracking, keyboard shortcuts, escape-to-cancel, and the “shake” feedback for tiny invalid selections.
4. Screen capture subsystem
- src/capture.rs wraps grim for screenshots.
- The design is optimized for perceived speed: it grabs the background screenshot before the GTK UI is fully up, then later produces the final cropped image from the user’s selection geometry.
5. Search and post-processing subsystem
- src/search.rs is the outbound integration layer.
- It branches into two distinct behaviors:
- Image-search mode: upload PNG data to an image host, then open the selected search engine URL in the browser.
- AI-chat mode: copy the captured PNG to the clipboard and open the configured chat URL, optionally auto-pasting with wtype.
6. External service dependency
- Reverse-image engines do not receive the image directly from the app; they need a reachable URL.
- The app therefore uploads to Imgur first, with a fallback to 0x0.st if that fails.
- AI chat mode intentionally skips upload and stays local until the browser handoff.
7. Configuration boundary
- src/config.rs reads and writes ~/.config/omarchy/circle-search.toml.
- Configuration controls which engine pills appear, their order, and AI-chat/upload settings.
- The config format is permissive: unknown keys are ignored so the file can evolve without breaking older versions.
8. Theme integration
- src/theme.rs reads Omarchy theme colors from ~/.config/omarchy/current/theme/colors.toml.
- This makes the overlay feel like part of the desktop rather than a standalone utility.
- Theming is a read-only dependency from the user’s existing Omarchy installation.
9. User feedback and notifications
- omarchy-notification-send is used for success/error feedback and optional completion notices.
- This is part of the app’s integration with Omarchy conventions rather than a generic desktop notification stack.
10. Clipboard, browser, and shell-tool dependencies
- The app relies on external command-line tools for key system interactions:
- wl-copy for clipboard writes
- xdg-open for opening search/chat URLs
- curl and python3 for upload/helper flows
- wtype for optional AI-chat paste/submit automation
- These tools are a key architectural boundary: Rust owns orchestration, but the actual desktop actions are delegated to established Unix utilities.
11. Main end-to-end data flow
- Startup: CLI/config/theme/dependency checks.
- UI: capture background screenshot, display overlay, collect selection and engine choice.
- Execution:
- crop region from screenshot
- either upload and open a search URL, or copy to clipboard and open chat
- Feedback: notify the user and exit.
12. Repository shape
- The codebase is intentionally small and split by responsibility:
- main.rs = orchestration
- overlay.rs = UI/input
- capture.rs = screenshot/cropping
- search.rs = external search/chat integration
- theme.rs = Omarchy styling
- config.rs = persistent user settings
- That separation maps cleanly to the architecture diagram: one interactive front-end, one capture pipeline, and one outbound integration layer.
Main entry points: main.rs main · search.rs search · overlay.rs overlay · capture.rs capture
Components 14
Orchestration
Startup, control flow, and app-wide coordination
- main · CLI entrypoint and control plane
src/main.rs
Interactive UI
Overlay and input handling
- overlay · Full-screen Wayland overlay and selection UI
src/overlay.rs
Capture & Outbound
Screenshot capture and post-selection actions
State & Styling
Persistent config and desktop theming
External Tools
Desktop utilities and remote services the app delegates to
- layer shell · Positions the overlay above the desktop
- grim · External screenshot backend
- Imgur · Primary upload target for reverse-image search
- 0x0.st · Backup upload target if primary upload fails
- wl-copy · Writes PNG data to the clipboard
- xdg-open · Opens search and chat URLs in the browser
- wtype · Optional automated paste and submit
- notify · Success, error, and completion feedback
Connections 15
- main → config: load/save · Reads user settings and persists updates
- main → theme: load · Loads desktop theme colors before UI startup
- main → overlay: start UI · Launches the full-screen selection overlay
- main → capture: prepare capture · Initializes screenshot capture for the session
- main → search: dispatch result · Routes the selected crop into image-search or AI-chat flow
- overlay → layer shell: present · Uses Wayland layer-shell for desktop overlay placement
- overlay → capture: request screenshot · Consumes the pre-captured background and selection geometry
- capture → grim: backend · Delegates screenshot capture to grim
- search → Imgur: upload · Primary image upload for reverse-image search
- search → 0x0.st: fallback · Uses backup host if primary upload fails
- search → wl-copy: copy png · Copies cropped image for AI-chat mode
- search → xdg-open: open url · Hands off to browser for search or chat
- search → wtype: auto paste · Optionally pastes and submits in chat mode
- main → notify: feedback · Emits success, error, and optional completion notices
- overlay → main: selection result · Returns chosen engine and capture geometry