---
title: Run a file from chat (right-click a runnable path → Run / Run as administrator)
---

# Run a file from chat (right-click a runnable path → Run / Run as administrator)

## What it is

When a chat message mentions a runnable file by its path — for example a PowerShell
fix script like `` `C:\tmp\amc-excl-fix-j.ps1` `` — Omniscio turns that path into something
you can run **without copying it into a terminal yourself**. Right-click the path and
pick **Run** or **Run as administrator**, and Omniscio launches it for you.

## Where to find it

### What you see

- In any chat message, a runnable file path is shown the same clickable way other
  file paths are (highlighted, in the accent color).
- **Right-click it** → a small menu with:
  - **Run** — runs the file.
  - **Run as administrator** — runs it elevated (Windows shows its normal "Do you want
    to allow this app to make changes?" UAC prompt; on a Mac it asks for your password).
    This option is hidden for file types that have no elevated form (a macOS `.app`).
  - **Reveal in folder** — opens the file's folder in your file manager.
- Before anything runs, a **confirmation dialog** shows you the **exact path** about to
  run. Nothing executes until you confirm. (Paths in chat can be written by the AI, so
  this is your chance to check it's what you expect.)
- When it launches, a **terminal window opens and stays open** so you can watch the
  output, and a toast confirms it ("Launching … — approve the prompt" for admin runs).

The two **Run** options only appear on files that are actually runnable on _your_
machine. A `.txt`, `.md`, or `.ts` path shows nothing new — it behaves as before.

## How it behaves

### What counts as "runnable"

- **Windows:** `.ps1`, `.bat`, `.cmd`, `.exe`, `.com`, `.msi`.
- **macOS:** `.sh`, `.command`, `.app`.

Windows types don't appear on a Mac and Mac types don't appear on Windows — the menu
matches the computer Omniscio is running on. (Linux is not covered yet.) Run is **desktop
only** — it does not appear when you're viewing Omniscio from the phone/web client, because a
script runs on the host computer, not your phone.

### A safety note about left-clicking

For programs and installers (`.exe`, `.msi`, `.com`, `.app`), a **left-click reveals the
file in its folder** rather than running it — running only ever happens through the
right-click menu and its confirmation. (Script files like `.ps1` still left-click to a
read-only preview of their contents.) This is deliberate: a single misclick should never
silently launch an installer.

### Why this is safe

- Omniscio never runs anything on its own — every run is an explicit right-click → confirm,
  and "Run as administrator" always passes through the operating system's own elevation
  prompt, which Omniscio cannot bypass.
- The command Omniscio hands to the operating system is built so a strange character in a path
  can't smuggle in an extra command (on Windows the whole command is encoded before
  launch; on macOS the path is quoted at both layers), and it never goes through a shell.
- The launched window is independent of Omniscio — your script keeps running even if you close
  Omniscio right after starting it (handy for a one-off fix script).
- It deliberately works for files **anywhere** on disk (the motivating case is a script in
  `C:\tmp`, outside any project), so the safety gate is _your confirmation of the exact
  path plus the OS prompt_, not a folder restriction.

### Limits (v1)

- Windows + macOS only.
- A path with spaces shown as inline code (e.g. `` `C:\Program Files\setup.msi` ``) is only
  detected inside a fenced code block or in prose, not as inline code — an inline-code path
  with spaces won't show the Run menu.
- Interpreter-based scripts run with the matching tool present (e.g. a macOS `.sh` runs via
  `bash`); the right-click Run on the popped-out (detached) session window is a follow-up.

## For agents

### For developers

- Single source of truth for "is this runnable + how is it launched":
  [src/shared/runnable-path.ts](../../src/shared/runnable-path.ts).
- The injection-safe launch builder (Windows `-EncodedCommand`; macOS `osascript`/Terminal
  with two-layer escaping):
  [src/main/ipc/file-handlers/run-script-launch.ts](../../src/main/ipc/file-handlers/run-script-launch.ts).
- The IPC handler that re-validates the path and spawns it:
  [src/main/ipc/file-handlers/run-script-handler.ts](../../src/main/ipc/file-handlers/run-script-handler.ts)
  (channels `FILES_REQUEST_RUN` — pops the native confirm + mints the capability token — then
  `FILES_RUN_SCRIPT` + `FILES_REVEAL_ABSOLUTE`).
- The confirmation is a **native OS dialog shown by Main** (not a renderer-drawn dialog, which an
  untrusted renderer could bypass); approving it mints a one-shot, path-bound capability token that
  `FILES_RUN_SCRIPT` requires before spawning (RT-F009):
  [user-gesture-capability.ts](../../src/main/ipc/user-gesture-capability.ts).
- The right-click menus live on the existing chat path elements
  ([AgentMarkdown.tsx](../../src/renderer/src/components/ui/AgentMarkdown.tsx) for inline-code
  and code-block paths, [agent-markdown-helpers.tsx](../../src/renderer/src/components/ui/agent-markdown-helpers.tsx)
  for bare-link paths); the action is centralized in
  [run-script-store.ts](../../src/renderer/src/stores/run-script-store.ts) (which drives the
  native-confirm → launch flow).
- Invariants + the tests that lock them:
  [run-chat-runnable-path-contract.md](../../.claude/memory/contracts/run-chat-runnable-path-contract.md).

## Related

Nothing else in the library covers this surface, so [INDEX.md](INDEX.md) — the library index — is the place to look for the neighbouring chat and file-handling pages if you want the wider picture of what a session's messages can do.