Skip to content
Back to search

omarchy-omapilot

OmaPilot - the native AI starting point for Omarchy Quattro

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/spencerbull--omarchy-omapilot/badge.svg)](/listings/spencerbull--omarchy-omapilot)

HTML

<a href="/listings/spencerbull--omarchy-omapilot"><img src="/api/listings/spencerbull--omarchy-omapilot/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Review the repository before enabling it: Omarchy plugins execute unsandboxed inside the long-lived shell process.

omarchy plugin add https://github.com/spencerbull/omarchy-omapilot.git
omarchy plugin validate ~/.config/omarchy/plugins/io.github.spencerbull.omapilot
omarchy plugin enable io.github.spencerbull.omapilot right

The Omarchy installer only clones, validates, and enables the plugin. Omarchy runs no plugin install hook, and OmaPilot does not request administrator access or invoke a package manager. Installation and first load do not edit Hyprland configuration. To add the described global shortcuts, explicitly choose **Settings → Desktop → Install global hotkeys**. OmaPilot then adds one marked block to `~/.config/hypr/bindings.lua` while preserving every shortcut chord already defined there. The reviewed repository revision includes reproducible Linux x86-64 broker and Codex ACP launchers, so a normal install does not run `npm`, `npx`, or silently download executable code. The launchers execute their embedded JavaScript payloads directly from the read-only launcher file with system Node; Git history anchors those generated files to their TypeScript source and pinned lockfile. Release archives add an SBOM, provenance record, and SHA-256 checksum.

Update or remove it with the standard plugin commands:

omarchy plugin update io.github.spencerbull.omapilot
omarchy plugin remove io.github.spencerbull.omapilot

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 487 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OmaPilot for Omarchy
  2. OmaPilot is a native [Omarchy Quattro](https://github.com/basecamp/omarchy/tree/quattro) bar widget and contextual-capture overlay for asking questions and working on your desktop through an authenticated AI harness. It can summarize the active window, research current information, clip a window or exact region, work through bounded app connectors, remember the latest 30 completed chats, and hand a conversation to Herdr when you want to keep going.
  3. The repository carries the `0.2.0` marketplace candidate under the permanent
  4. plugin ID `io.github.spencerbull.omapilot`. Its plugin, IPC, package, runtime,
  5. and user-data identifiers consistently use the OmaPilot namespace.
  6. ## Preview
  7. ![OmaPilot ambient voice listening on a blank workspace](screenshots/omapilot-voice-active.gif)
  8. Ambient voice stays out of the way until it has something useful to show. The
  9. listening surface above is the real animated `VoiceNode` component recorded on
  10. an isolated blank workspace.
  11. ![OmaPilot main screen in a new chat](preview.png)
  12. The new-chat screen is rendered from the current QML components against the
  13. pinned Omarchy Quattro imports with `npm run preview`; the same panel and
  14. components are exercised by the UI contract suite and verified in the live
  15. shell.
  16. The compact composer expands from the right side of the bar. Device changes
  17. stay behind an exact, inspectable approval unless you explicitly enable
  18. **Dangerous auto-approve** in settings. Its result panel
  19. supports selectable Markdown, code blocks, tables, safe clickable links,
  20. bounded images, Copy, New chat, History, and Continue in Herdr. The in-panel
  21. settings pane can add, edit, remove, and reorder up to five quick actions.
  22. Built-in follow-ups resume the same durable Pi conversation until **New chat**
  23. is selected, including after the shell restarts. **Continue in Herdr** opens
  24. that same Pi session with OmaPilot's private auth and session directories.
  25. Waiting and streaming use one theme-native perimeter runner around the response
  26. surface. One GPU-blurred accent form replaces the old route glyph without a
  27. separate hard stroke or fake progress; phase changes never restart the runner,
  28. and reduced motion keeps the ordinary static border. First-token
  29. content, panel growth, and follow-latest scrolling transition smoothly, while a
  30. compact error notice opens an inspectable details pane.
  31. ## Requirements
  32. - Omarchy Quattro with the native shell plugin architecture.
  33. - Linux x86-64 for the initial prebuilt runtime.
  34. - Node.js 22 or newer. The checked-in Linux launchers contain the reviewed
  35. broker and Codex ACP payloads but execute them with the system Node runtime.
  36. - Credentials for the built-in harness, or an installed and authenticated ACP harness.
  37. - Optional: Voxtype for dictation and Herdr for durable continuation.
  38. - Optional: a TTS provider to speak answers. ElevenLabs is the guided default
  39. and needs an API key entered in Settings. Kokoro is local
  40. (`pip install kokoro soundfile` on Python 3.10–3.12, plus `espeak-ng`), while
  41. OpenAI also needs an API key. Cloud keys are stored
  42. in `~/.config/omapilot/voice-auth.json`, not widget settings. Voice stays
  43. off until enabled there.
  44. - `grim` for contextual screenshots. ImageMagick, already used by OmaPilot's
  45. image policy, validates and normalizes every captured image.
  46. - Optional: Tesseract adds text-under-the-pointer extraction and the **Text**
  47. representation. Without it, screenshot and browser-element capture still work.
  48. OmaPilot includes a native Pi-based harness for Codex subscription, OpenAI API,
  49. Grok, and configured OpenAI-compatible endpoints. It resolves credentials from
  50. environment variables or `${XDG_CONFIG_HOME:-$HOME/.config}/omapilot/auth.json`,
  51. discovers shared `~/.agents` skills, Omarchy's official `~/.pi/agent/skills`
  52. root, bundled OmaPilot skills, and named agents. It exposes Pi's standard coding
  53. tools plus verified app, window, workspace, and monitor controls behind
  54. OmaPilot's approval broker. See [Native Pi harness configuration](docs/native-harness.md).
  55. The Harness setting explicitly selects **Built-in (OmaPilot)**, **Codex**, or
  56. **OpenCode**. The latter two are ACP harnesses and must already
  57. be installed and signed in. OmaPilot never substitutes one harness for another.
  58. When Built-in has no configured credential, its settings card offers
  59. subscription and API-key sign-in methods. OmaPilot runs Pi's typed login flow
  60. inside the broker, opens the provider's browser page for OAuth when needed, and
  61. renders provider choices, device codes, progress, and errors in Settings.
  62. Browser OAuth completes through a broker-owned localhost callback; callback
  63. URLs are never user input. It never opens the Pi terminal.
  64. After authentication, the empty conversation shows the next first-run step:
  65. configure Voice with ElevenLabs, then open Desktop settings and explicitly press
  66. **Install global hotkeys**. Chat remains usable throughout; setup never edits
  67. Hyprland configuration without that final button press.
  68. ## Install
  69. Review the repository before enabling it: Omarchy plugins execute unsandboxed inside the long-lived shell process.
  70. ```bash
  71. omarchy plugin add https://github.com/spencerbull/omarchy-omapilot.git
  72. omarchy plugin validate ~/.config/omarchy/plugins/io.github.spencerbull.omapilot
  73. omarchy plugin enable io.github.spencerbull.omapilot right
  74. ```
  75. The Omarchy installer only clones, validates, and enables the plugin. Omarchy
  76. runs no plugin install hook, and OmaPilot does not request administrator access
  77. or invoke a package manager. Installation and first load do not edit Hyprland
  78. configuration. To add the described global shortcuts, explicitly choose
  79. **Settings → Desktop → Install global hotkeys**. OmaPilot then adds one marked
  80. block to `~/.config/hypr/bindings.lua` while preserving every shortcut chord
  81. already defined there. The reviewed repository revision includes
  82. reproducible Linux x86-64 broker and Codex ACP launchers, so a normal install
  83. does not run `npm`, `npx`, or silently download executable code. The launchers
  84. execute their embedded JavaScript payloads directly from the read-only launcher
  85. file with system Node;
  86. Git history anchors those generated files to their TypeScript source and pinned
  87. lockfile. Release archives add an SBOM, provenance record, and SHA-256 checksum.
  88. Update or remove it with the standard plugin commands:
  89. ```bash
  90. omarchy plugin update io.github.spencerbull.omapilot
  91. omarchy plugin remove io.github.spencerbull.omapilot
  92. ```
  93. ## Global hotkeys
  94. OmaPilot exposes compositor-safe IPC actions for a contextual voice session,
  95. forced-fresh typed or voice conversations, and handing the current chat to
  96. Herdr. Choose **Settings → Desktop → Install global hotkeys** to add these
  97. bindings to `~/.config/hypr/bindings.lua`, where their descriptions appear in
  98. **Learn → Keybindings**:
  99. ```lua
  100. -- Start fresh when the ambient flow is closed; continue while it is visible.
  101. o.bind("SUPER + A", "Talk to OmaPilot",
  102. "omarchy-shell -q io.github.spencerbull.omapilot voiceToggle")
  103. -- Force a fresh voice chat, even while the ambient flow is still active.
  104. hl.unbind("SUPER + SHIFT + A")
  105. o.bind("SUPER + SHIFT + A", "New OmaPilot voice chat",
  106. "omarchy-shell -q io.github.spencerbull.omapilot newVoiceChat")
  107. o.bind("SUPER + ALT + X", "Cancel OmaPilot voice mode",
  108. "omarchy-shell -q io.github.spencerbull.omapilot voiceCancel")
  109. o.bind("SUPER + ALT + N", "New OmaPilot chat",
  110. "omarchy-shell -q io.github.spencerbull.omapilot newChat")
  111. o.bind("SUPER + ALT + H", "Continue OmaPilot chat in Herdr",
  112. "omarchy-shell -q io.github.spencerbull.omapilot continueInHerdr")
  113. ```
  114. `Super+A` starts a new durable conversation whenever the ambient node and answer
  115. curtain have closed. While that flow remains active, pressing it again finishes
  116. live dictation or begins a follow-up in the same conversation. The answer timer,
  117. explicit dismissal, and cancellation close the voice session; they do not erase
  118. its saved history. `Super+Shift+A` remains the force-new escape hatch, while
  119. `Super+Alt+X` cancels and closes the active voice flow. New typed chat opens the
  120. panel with an empty composer. Continue in Herdr does nothing until the current
  121. conversation has a saved chat ID.
  122. The managed block is written only after that explicit action and becomes normal
  123. user-owned Hyprland configuration. Existing user-defined collisions are left
  124. alone. Running the installer again adds newly introduced defaults to its marked
  125. block without rewriting existing bindings. To install from a terminal while
  126. still preserving collisions, or to deliberately replace every chord, run:
  127. ```bash
  128. ~/.config/omarchy/plugins/io.github.spencerbull.omapilot/scripts/install-hotkeys.sh
  129. ~/.config/omarchy/plugins/io.github.spencerbull.omapilot/scripts/install-hotkeys.sh --force
  130. ```
  131. Before removing the plugin, remove only its managed block, then use Omarchy's
  132. standard removal command:
  133. ```bash
  134. ~/.config/omarchy/plugins/io.github.spencerbull.omapilot/scripts/install-hotkeys.sh --remove
  135. omarchy plugin remove io.github.spencerbull.omapilot
  136. ```
  137. Removal deletes the cloned plugin. OmaPilot deliberately leaves user-owned history and cached runtime files in place. Use **Clear all** before removal to erase history and cached chat images. If the plugin is already gone, inspect and remove the OmaPilot directories under your effective `XDG_STATE_HOME` and `XDG_CACHE_HOME` with a file manager; the default locations are `~/.local/state/omapilot` and `~/.cache/omapilot`.
  138. ## How it works
  139. ```text
  140. Omarchy BarWidget/Panel
  141. │ submit-time Hyprland/MPRIS snapshot
  142. │ one JSON command/event per line
  143. ▼
  144. OmaPilot broker
  145. ├── Built-in (selected) ─ Pi runtime ─ Codex / OpenAI / Grok / compatible APIs
  146. ├── Codex (selected) ─── Codex ACP
  147. └── OpenCode (selected) ─ OpenCode ACP
  148. ```
  149. The native runtime owns model discovery, auth resolution and refresh, skills,
  150. named agents, streaming, and Pi tool execution. The explicitly selected Codex
  151. ACP route uses an exact, source-pinned adapter package; OpenCode uses `opencode acp`.
  152. The broker normalizes both paths so QML does not parse provider-specific output.
  153. Every request uses the selected harness and its reviewed automatic policy.
  154. OmaPilot displays each exact device approval, or auto-selects its allow-once
  155. option when the dangerous setting is enabled.
  156. Every harness can load relevant installed skills and decide whether a tool is
  157. needed:
  158. - **Built-in (OmaPilot)** combines available Codex, OpenAI, Grok, and
  159. OpenAI-compatible models in one catalog and loads
  160. declarative skills from `~/.agents/skills`, `~/.pi/agent/skills`, project
  161. skill roots, and this plugin's bundled `skills/` directory, plus named agents
  162. from the documented `~/.agents` roots. Its structured desktop tools discover
  163. exact installed apps and current Hyprland targets, then verify app focus or
  164. launch, window focus/move/resize/float/close, and workspace focus or monitor
  165. movement before reporting success.
  166. The **Skills** settings tab also reports personal capability packs for Email,
  167. Calendar, Files, Projects, Messages, and Meetings. Ready packs add typed tools
  168. for HEY, one configured files root, the official Basecamp CLI, a private
  169. loopback Signal bridge, and validated Zoom links. Bundled domain skills teach
  170. the agent when to use those tools and how to treat app content as untrusted.
  171. Pi's read, grep, find, and list tools may read files available to the current
  172. user. Bash, edit, and write require review unless an exact session or durable
  173. grant already exists. Executable Pi extensions are not loaded.
  174. - **Codex ACP** may use its read-only device tools and read files available to the
  175. current user without asking. Native web search stays disabled in the same
  176. session so those reads cannot become unapproved search queries. Any command
  177. requesting network or broader device authority pauses behind a card showing
  178. the adapter-normalized command, working directory, and every provider-native
  179. once, session, durable, or rejection choice supplied by the adapter.
  180. OmaPilot also attaches a fixed local MCP server containing only the capability
  181. registry and the packs' bounded read operations. It does not expose sends,
  182. file opens, or meeting launches to ACP.
  183. - **OpenCode ACP** may load installed skills and use its positively identified web
  184. search tool automatically. Its native `bash` permission is fixed to `ask`;
  185. the broker accepts execution only after the exact command receives a
  186. request-bound **Allow once** decision. Other OpenCode tools remain denied.
  187. Every supported permission decision is bound to a provider option. Native Pi
  188. session and durable grants match only the exact reviewed request and working
  189. directory. Oversized or visually ambiguous requests, arbitrary provider-supplied MCP,
  190. browser/computer control, unclassified tools, and uninspectable targets remain
  191. blocked. OmaPilot removes its per-turn working directory afterward. Raw tool
  192. requests, decisions, inputs, and outputs are not stored in chat history; a
  193. completed answer may contain tool- or web-derived text and is retained normally.
  194. OmaPilot never bypasses a harness permission system. When **Dangerous
  195. auto-approve** is enabled, a submission automatically selects only the
  196. normalized request's provider-native **Allow once** choice instead of showing
  197. the approval card. The setting cannot select a persistent grant and does not
  198. enable tools for a harness whose provider policy blocks them. It is off by
  199. default because approved commands run with the authority described above and
  200. may modify or delete user data or use the network.
  201. The broker does not classify prompt phrases or hardcode individual use cases.
  202. Questions and action requests follow the same provider path; the selected
  203. harness decides whether a tool is useful. Any broader device command remains
  204. inside the exact request-bound decision described above, whether that decision
  205. is made from the approval card or by Dangerous auto-approve.
  206. Each harness receives the same hidden OmaPilot instructions. They frame desktop
  207. context as optional, untrusted evidence; direct the harness to discover relevant
  208. installed skills, Omarchy commands, CLIs, apps, and plugins before declining;
  209. prefer the system default browser for authorized navigation; and use available
  210. web search for current or otherwise unknown information. These instructions
  211. shape how a harness chooses among capabilities but cannot enable a capability
  212. or bypass the provider policy and approval boundary above.
  213. ## Personal capability packs
  214. Open **Settings → Skills** to see connector readiness, enable or disable a pack,
  215. refresh status, and choose the one folder Files may inspect. Pack configuration
  216. is broker-owned and validated; missing applications, authentication, and pairing
  217. are reported as setup states rather than installed or changed automatically.
  218. The built-in defaults are:
  219. - Email and Calendar through authenticated `hey-cli`;
  220. - Files inside one canonical local or synced folder, without following symlinks
  221. outside that root;
  222. - Projects through the authenticated official `basecamp` CLI;
  223. - Messages through `signal-cli-rest-api` only when
  224. `OMAPILOT_SIGNAL_API_URL` is an HTTP loopback origin and
  225. `OMAPILOT_SIGNAL_NUMBER` is a linked E.164 number; and
  226. - Meetings through an exact HTTPS `zoom.us` URL opened with Omarchy.
  227. Read operations return bounded data marked as external and untrusted. Visible
  228. device actions use the normal exact approval. Email, HEY to-do, Basecamp, and
  229. Signal writes are stricter: they always require a fresh one-time review and are
  230. never covered by a session grant, durable grant, or Dangerous auto-approve.
  231. Codex receives the registry and bounded read-only pack tools through OmaPilot's
  232. bundled MCP server. OpenCode receives connector reads but no Files tools, which
  233. preserves its fixed no-host-reads policy. Mutations remain exclusive to the
  234. built-in Pi harness until ACP can preserve the same one-shot contract.
  235. ## Installed apps and Omarchy commands
  236. Built-in OmaPilot can browse or search installed graphical apps and executable
  237. CLI programs with `app_catalog`; this inventory is separate from submit-time
  238. desktop context, which reports only currently open apps. It can also search the
  239. installed system's documented `omarchy commands --json` catalog with the
  240. read-only `omarchy_commands` tool. Finding a command does not execute it:
  241. structured actions remain preferred, and any shell fallback keeps the normal
  242. exact approval boundary.
  243. ## Browser search handoff
  244. Built-in OmaPilot can hand a current-information question to a browser without
  245. adding a paid search API. Choose **Settings → Desktop → Search provider** and
  246. select DuckDuckGo, Google, ChatGPT Search, Claude, or Grok. The `web_handoff`
  247. tool shows an approval card with the provider, exact question, and destination
  248. URL, then opens it through `omarchy launch browser`.
  249. DuckDuckGo and Google receive a normal search query. AI sites receive a
  250. search-oriented prompt in their URL and a paste-ready clipboard copy as a
  251. fallback because their web composers may not reliably prefill. This is an
  252. interactive handoff: OmaPilot reports that the browser opened, but it does not
  253. read, synthesize, or verify the answer shown there. OpenCode's native search,
  254. when available under its own policy, remains separate from this setting.
  255. ## Desktop context on submit
  256. Desktop context is **On** by default and can be disabled in the widget's
  257. Omarchy settings. OmaPilot remembers the active app as its panel opens (before
  258. the panel takes keyboard focus), then reads the remaining public Quickshell
  259. objects when you send. It attaches:
  260. - the active window's app ID, title, workspace, and monitor;
  261. - up to 12 deduplicated open-app IDs with window counts and workspace IDs; and
  262. - player identity, track title, and artist for up to four currently playing MPRIS sources.
  263. OmaPilot does not capture compositor window handles, inactive window titles,
  264. screenshots, clipboard contents, page bodies, hidden browser tabs, browser
  265. history, keystrokes, or file contents as desktop context. A browser's current
  266. tab may be recognizable only when the browser exposes it in the active window
  267. title.
  268. Window and media strings are length-bounded, stripped of control and
  269. bidirectional-display characters, and labeled as untrusted observational data
  270. before being sent to the harness. The selected harness still decides whether
  271. the context is relevant and whether a tool is needed. OmaPilot stores the
  272. original question—not the snapshot—in its chat record, but the selected
  273. provider receives the combined prompt and may retain it in its native session.
  274. An answer derived from desktop context is retained like any other completed
  275. answer.
  276. ## Clip context from the desktop
  277. The crosshair button in the composer opens OmaPilot's fullscreen capture
  278. overlay. Click a window beneath the pointer, or drag an exact region. OmaPilot
  279. resolves the click against the compositor's window geometry, so opening the
  280. panel or overlay does not change the intended target. The overlay disappears
  281. before the screenshot is taken.
  282. When Tesseract is installed, OmaPilot uses its word boxes to find the text under
  283. the click and expands it to the surrounding paragraph. The composer then shows
  284. a local thumbnail and a selector with the representations actually available:
  285. **Text**, **Screenshot**, or **Text + screenshot**. OCR failure is not an error;
  286. the validated screenshot remains the fallback. Removing the attachment deletes
  287. its broker-owned input image, and submitting sends only the selected
  288. representation—not every locally generated alternative.
  289. Context clips are explicit and single-shot. OmaPilot does not continuously
  290. watch the pointer, index accessibility trees, monitor the clipboard, or capture
  291. screens in the background. Password-manager and password-like windows are
  292. blocked conservatively. Clip text and pixels are framed as untrusted
  293. observational data and do not expand tool authority.
  294. ## Storage and privacy
  295. OmaPilot persists only completed chats, capped at the newest 30. A chat contains the question, rendered answer source, timestamp, provider/model metadata, content references, and a resumable session identity when the harness supplies one. Draft text, authentication output, tokens, environment variables, and provider credentials are not persisted.
  296. Quick-action labels, prompts, and order are stored with the existing inline
  297. Omarchy widget settings. OmaPilot validates that list on every read, drops
  298. invalid entries, and caps it at five.
  299. | Path | Purpose |
  300. | --- | --- |
  301. | `${XDG_STATE_HOME:-~/.local/state}/omapilot/` | Atomic local history and durable Pi conversation sessions |
  302. | `${XDG_CONFIG_HOME:-~/.config}/omapilot/capabilities.json` | Enabled packs and the canonical Files root (mode 0600) |
  303. | `${XDG_CACHE_HOME:-~/.cache}/omapilot/` | Bounded, validated image cache |
  304. | `${XDG_RUNTIME_DIR}/omapilot/` | Per-login sockets, temporary dictation, and in-flight data |
  305. Remote Markdown images are not fetched automatically. OmaPilot shows the origin and requires a click before loading a validated HTTPS image. Links are scheme-checked and never interpolated into a shell command. See [`SECURITY.md`](SECURITY.md) for the threat model and reporting process.
  306. ## Optional integrations
  307. - **Voxtype:** when `voxtype` is installed and ready, the microphone records directly to a file under `$XDG_RUNTIME_DIR/omapilot`; OmaPilot reads that transcript after recording stops. It never simulates keyboard input or modifies Voxtype configuration.
  308. - **Herdr:** when `herdr` is installed, Continue in Herdr launches it when needed or raises its existing window, creates or reuses the `OmaPilot` workspace, creates a labeled tab, closes the OmaPilot panel, and focuses the resumed agent pane. It resumes the native harness session when possible, otherwise starts the matching agent with a compact transcript and labels the fallback. A native resume retains whatever context the provider kept in that session; a transcript fallback receives only the stored question and answer, not the raw desktop snapshot. This is an explicit handoff from OmaPilot's one-shot permission boundary to Herdr's normal native-agent permission model; Codex resumes read-only and asks before commands.
  309. Both integrations disappear or show a clear unavailable state when their required command is missing.
  310. ## Browser element context
  311. The optional **OmaPilot Browser Companion** adds semantic page clipping to the
  312. same crosshair button. On a site the user has enabled, OmaPilot closes its
  313. desktop overlay and the page itself highlights the element beneath the pointer.
  314. Clicking produces bounded **Element**, **Text**, and **Screenshot** choices; on
  315. an unsupported, restricted, or non-enabled page, the existing desktop capture
  316. opens instead.
  317. The companion is one WebExtension source with Chromium and Firefox builds plus
  318. a small local native-messaging relay. It supports Omarchy's Chromium, Chrome,
  319. Brave, Brave Origin, Edge, Vivaldi, Helium, Firefox, Zen, and LibreWolf browser
  320. families. Its rules are:
  321. - the Omarchy plugin remains fully useful without the extension;
  322. - context is visibly disclosed and captured only after an explicit clip request and page click;
  323. - page access is opt-in and scoped per site, with no browsing-history collection;
  324. - the bridge accepts a small versioned schema and does not expose a general command channel; and
  325. - the extension avoids Chrome's broad `debugger` permission and requests only the minimum tab/site/native-messaging permissions needed for enabled features.
  326. Native messaging requires registration outside the plugin directory, so it is
  327. enabled only with the user's explicit consent. The primary setup path does not
  328. require a terminal: open **OmaPilot settings → Desktop** and choose
  329. **Enable browser context**. OmaPilot registers the user-local relay and adds the
  330. bundled unpacked extension to detected Omarchy Chromium-family browser flags.
  331. Restart the browser afterward, pin the OmaPilot extension, then choose **Enable
  332. on this site** once for each site where DOM capture should be available.
  333. Firefox and Zen development builds still require browser confirmation to load
  334. `browser-companion/dist/firefox` temporarily; browsers do not allow another
  335. application to silently install an unsigned temporary extension. Expand
  336. **Finish browser setup** in OmaPilot settings to open the correct Chromium or
  337. Firefox extension page and copy the matching bundled folder path. The same
  338. controls remain available as a manual fallback when a Chromium-family browser
  339. does not honor its unpacked-extension flag.
  340. The script remains available for development, diagnostics, and removal:
  341. ```bash
  342. ./scripts/install-browser-companion.sh install
  343. ```
  344. For local Omarchy Chromium-family development, it can add the unpacked build to
  345. detected browser flag files:
  346. ```bash
  347. ./scripts/install-browser-companion.sh install --development
  348. ```
  349. The primary removal path is also in settings. Choose **Remove browser context**
  350. and confirm before removing the OmaPilot plugin. This removes the user-local
  351. relay, native-messaging manifests, and unpacked-extension browser flags. Restart
  352. open browsers afterward to unload the already-running extension process.
  353. Omarchy deliberately does not execute plugin install or removal hooks, so
  354. `omarchy plugin remove` cannot invoke OmaPilot's cleanup automatically. Remove
  355. browser context from settings first. The script remains available for recovery
  356. or development if the plugin has not yet been removed:
  357. ```bash
  358. ./scripts/install-browser-companion.sh uninstall
  359. ```
  360. The desktop capture feature needs no separate OmaPilot package: its QML,
  361. broker code, and built browser assets ship in the plugin repository. A durable
  362. browser release does need two additional delivery channels because browsers do
  363. not permit a plugin clone to install them silently:
  364. 1. publish the Chromium and Firefox builds through their browser extension
  365. stores so users receive a stable extension ID and browser-managed updates;
  366. 2. keep the tiny native relay in this repository initially, with an explicit
  367. install/uninstall command, then package that relay separately (for example as
  368. an AUR package) if automatic upgrades and ownership tracking are desired.
  369. The relay and extension have no additional npm dependencies. The current relay
  370. installer uses the already-required Node.js runtime plus `jq` to write native
  371. messaging manifests. Store-packaged extensions can share the same versioned
  372. wire contract and release from the existing source; they do not require a
  373. separate source repository.
  374. The element representation is a capped semantic tree—not raw `outerHTML`—and
  375. omits editable values, editable accessible-name fallbacks, selections rooted in
  376. editable content, password content, hidden nodes, scripts, styles, event
  377. handlers, query strings, and fragments. Each capture remains bound to the exact
  378. tab and native-relay session that answered its probe. Browser actions remain
  379. out of scope; they would need their own inspectable per-action approval boundary.
  380. ## Development
  381. ```bash
  382. ./scripts/validate.sh
  383. ./scripts/package-runtime.sh --dry-run
  384. npm run preview
  385. ```
  386. After the broker has been built, assemble a local release artifact without publishing it:
  387. ```bash
  388. npm ci
  389. npm run build
  390. ./scripts/package-runtime.sh --output-dir dist/release
  391. ```
  392. Runtime builds require Linux x86-64 and Node.js 22 or newer. The package helper
  393. stages the self-contained checked-in runtime, emits a
  394. lockfile-derived CycloneDX SBOM, normalizes timestamps and ownership, creates a
  395. deterministic archive, and writes `SHA256SUMS`. Release details and marketplace
  396. gates are in [`docs/release.md`](docs/release.md).
  397. ## License and attribution
  398. OmaPilot is MIT licensed. ACP adapters and bundled dependencies retain their own licenses; see [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) and the generated release SBOM.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.