Deep Links (omniscio:// URLs)
Omniscio's custom link protocol: the omniscio:// URLs that open the app and jump straight to one inbox approval, project, session, note, mind map, setting, Supermail thread, calendar event or team-chat message, plus the older agentmc:// form still accepted on the way in. Covers every route, how to build the links, and what the same links do on a phone.
On this page
What it is
Omniscio registers itself with your OS as the handler for its custom link protocol, so a deep link — clicked from an email, pasted into a terminal, written in a Slack message, rendered inside the app itself — opens Omniscio and navigates to the exact view you specified. Two schemes, one behavior: links the app now builds (Copy-link buttons, agent-emitted links, dashboard/email links) carry the brand omniscio:// scheme (instance-suffixed to omniscio-<id>:// on a dev/sandbox instance so the link stays routable while that instance runs); the older agentmc:// scheme is still accepted on the way in, so an existing agentmc://… link a user saved keeps routing. The parser accepts either base — so both omniscio://session/<id> and agentmc://session/<id> land on the same view.
The routes are: inbox, a specific inbox card (omniscio://inbox/item/<id> — opens the inbox on that exact card, whether it is a pending approval or an alert; for an approval, resolving it returns you to the session that requested it), a specific inbox alert (omniscio://alert/<id> — the canonical form of the alert case, and the link POST /alert returns to the agent that raised the card, so an agent never has to guess; unlike an approval there is no return-to-session step when you deal with it), a specific project (fuzzy-matched by name), new session in a project (optionally with the first message pre-filled), a specific session by id (optionally scrolled to a message), a specific KMS note (by vault-relative path), an automation rule (omniscio://automation/<id> — opens the rule, or its approval pane while it waits for approval) and a scheduled job (omniscio://cron/job/<id> — opens the job where Approve sits), a Nighty Tidy audit run (omniscio://nighty-tidy/run/<runId> — opens that run's report), a mind map (by id), a specific setting (by id, section, or fuzzy phrase — opens Settings and scrolls to + flashes the row), a Super Prompt (omniscio://superprompt/<id> — opens the Super Prompts picker on that prompt), an Arij route (omniscio://arij/<path...> — opens the Arij area on that route), three Ollert routes — open an invitation (omniscio://trello/invite/<token>), jump to a board (omniscio://trello/board/<boardId>), and jump to a card (omniscio://trello/card/<boardId>/<cardId>), two Mission Control routes — join a shared board/workspace/dashboard (omniscio://monday/join/<kind>/<token>) and complete an invitation (omniscio://monday/invite/<token>), a team chat message link (omniscio://chat/<kind>/<wsId>/<channelId>?message=<msgId>), a Supermail email thread (omniscio://supermail/thread/<threadId> — opens that email in the Supermail panel), a calendar event (omniscio://calendar/event/<eventId>?calendar=<calendarId> — opens that event's details in the Calendar panel), and — on any navigate-only route — an optional ?highlight=<anchor> query that spotlights a specific [data-ui-anchor] control after the view mounts (e.g. omniscio://setting/cli-control?highlight=cli-control-regenerate navigates to the CLI Control settings page and rings the Regenerate button). Deep links are the cheap, scriptable way to wire Omniscio into anything — AutoHotkey hotkeys, cron jobs, Obsidian notes, bookmarks, email signatures — without a token or HTTP call. The setting route is also how an Omniscio agent hands you a one-click jump to the exact toggle it's talking about: it writes omniscio://setting/<id> in chat and clicking it takes you straight there (it only navigates — you still flip the switch yourself).
Where to find it
There is nothing in the interface to open — deep links are a convention, not a screen. You use one by putting it wherever a URL can go: a bookmark, an AutoHotkey hotkey, a note, an email, or a terminal. Inside the app, the places that hand you one (a message's share icon, an approval card, a setting an agent mentions in chat) do so as a clickable link, so the only thing you have to supply yourself is the address.
How it behaves
How to use it
Open the inbox.
omniscio://inbox— no arguments. Good for a taskbar shortcut or a "catch up" bookmark. (agentmc://inboxstill works too.) Jump straight to one card:omniscio://inbox/item/<id>opens the inbox and lands on that specific card — a pending approval or an alert (<id>is the card's row id). It is the generic spelling;omniscio://alert/<id>is the canonical form of the alert case and the onePOST /alerthands out. A link to an approval that has already been handled tells you how it ended and when — "Already approved at 3:38 PM." (or denied, cancelled, expired or closed), in your own clock — instead of opening anything; a link to any other card that is no longer in the inbox (or never was) says it couldn't open that card. Either way it never leaves you somewhere else on the list. This is the link the CLI approval gate hands the agent that queued the approval (it now rides in the202create response), so an agent can give you a one-click "approve this" link. Arriving via the link is special: when you approve or reject the approval, Omniscio returns you to the session that requested it — whereas resolving the same approval the normal way in the inbox just advances to the next approval (no session jump). It's navigate-only (no spawn/send), so it isn't approval-gated itself. A malformed link (no id) lands on the inbox with a graceful empty pane rather than erroring. See settings-patch-approval.md and approvals-hub.md.Jump to a project.
omniscio://project/<ref>—<ref>is a display name, the project's id, or its sentinelfolderPath(__cronjobs__); all three are exactly whatGET /projectsprints for it. Matching is tiered, and every EXACT tier outranks every fuzzy one: exact name → id → sentinel path → friendly alias → starts-with → unique contains → lone accent-fold. The friendly aliases are the same short namesGET /project/<name>takes (omni,monday,mission-control,dev-pipeline,team-chat,cron,digest, …; spaces and hyphens fold to underscores), so a link and the CLI route land on the same panel; an alias never beats a project whose name matches exactly, and an alias whose panel is not in your list falls through to the fuzzy tiers. Omni has a link:omniscio://project/omniopens Omni's page, and?view=projects|sessions|what-changed(orproject:<key>/suggestion:<key>) lands it on that tab or row — the same hintsGET /project/omni?view=takes. A Dev Pipeline link (omniscio://project/dev-pipeline?view=<tab>) carries its tab the same way.GET /deep-link/resolvenames the project a project link opens in amatchedfield, so a dry-run shows whetheromnilands on Omni rather than on a repo whose name starts with "omni". Soomniscio://project/apipicksApi-Gatewayif that is your only project containingapi, while an id can never lose to a prefix hit on some other project. Every project the app lists is reachable, virtual panels (Settings, Cron Jobs, Inbox Pilot, …) included — this link only navigates, and the app can navigate to all of them. The narrower spawnable-only filter still applies to…/newbelow (you cannot start a session inside__settings__) and toPOST /project/<name>/new; before 2026-09-09 that spawn filter was wrongly applied to plain navigation too, which madeGET /deep-link/resolvereport real projects — and every project id — as broken links. A Tasks link can name its view:omniscio://project/__tasks_v2__?view=todayopens Tasks on its Today view (any otherviewvalue, or the hint on any other project, is ignored). This is how Open Today in a popped-out Mission Control window reaches the main window: a pop-out shows only its own screen, so it sends this link and the main window switches itself to Today.Start a new session with a prompt.
omniscio://project/<name>/new?prompt=<url-encoded prompt>. Omniscio opens the project and launches a new session with the prompt pre-populated, ready to send. The prompt parameter is optional — without it you just get an empty new session. A deep link always asks first: the request lands in your inbox as an approval row ("New session from AI") showing the project and a preview of the prompt, and the session starts when you approve it — nothing is spawned before that. This is deliberate, and it is the same policy the Super Prompt link above follows (an external link lands on the picker; it never auto-runs). A URL is not a gesture you made inside the app: the scheme is registered with your OS, so a page or an email can ask you to open one, and the prompt in it is written by whoever built the link. Approving is what makes it yours. Once approved the spawn is a background one — the sidebar gets a new row and your current view doesn't change — and a bottom-left toast announces it: the first few words of your prompt right away, then the session's AI-generated title once that lands (about 3 seconds), so you can tell at a glance which session just started; click its Open button to jump to it. For AI-initiated spawns that come from somewhere other than a link — an authenticatedPOST /project/<name>/newfrom the CLI, a cron job, another session — the gate is the Settings → CLI Control → "Require approval for AI session spawns" toggle, which is off by default; turn it on and those land in the same inbox row ("New session from AI"), the same way cron / automation / agent-driven-spawn approvals work. Inside the app,…/new?draft=1&prompt=<text>behaves differently: an agent's chat message or an inbox card writes it (the maintenance report's Pick it up buttons are these), and clicking it opens a new session in front of you with the text pre-filled as an unsent draft — no approval row, because nothing is sent or spent until you press send. If the app cannot start that session, an error toast says why instead of the click doing nothing. A prompt link can carry more than the prompt (the full guide is Prompt links):repo=<owner/name>picks the project whose GitHub repository that is when no project has the name in the link (omniscio://new?prompt=…&repo=<owner/name>names no project at all),pr=<pull request address or owner/name#12>names a pull request, andprovider=<engine>withmodel=<model>starts the session on that engine and model. A prompt with invisible characters in it (zero-width spaces, direction overrides and the like, a common way to hide instructions) is no longer refused: the characters are removed and the approval row says how many were taken out, so read the prompt before you approve.Link directly to a session.
omniscio://session/<id>— where<id>is the session's UUID (optionally?message=<msgId>to scroll to a specific message). Used internally by markdown rendering (the search palette and agent messages render this format as a clickable link) and externally for any place you want to hand someone a stable pointer to one conversation. Added to unblock linking from search results. A link label may carry its own square brackets —[[Release] Overseer #1](omniscio://session/<id>)is one clickable, copyable link (before 2026-10-09 such a label rendered as a dead link with an empty target).Open a specific KMS note.
omniscio://note/<vault-relative-path>(optionally?vault=<vaultId>). Omniscio activates the KMS panel and opens that note as a tab — e.g.omniscio://note/Architecture.mdoromniscio://note/One-on-Ones/Brett.md(sub-folders work as real/separators or a single%2F-encoded segment; spaces percent-encode as%20). It's non-destructive (no spawn, no send), so it isn't approval-gated. A cold click (KMS not open yet) still lands — the request is held until the vault finishes loading. Requires KMS to be enabled (Settings → Features → Enable KMS); a disabled KMS, or a path that no longer matches an indexed note, surfaces a toast instead of opening a blank tab.Open a mind map.
omniscio://mindmap/<id>— opens the Mind Map panel and loads the map with the given id. The id is the same one returned by the mind-map library or the CLI create/import routes; the link is percent-encoded and decoded by the parser. Requires the Mind Map feature to be on (Settings → Features → Mind Map).Open a setting.
omniscio://setting/<id>— opens Settings, navigates to the right section, then scrolls to and briefly flashes the matching row.<id>can be any of four things, because different callers hold different names for the same setting: an exact setting id (preload-sessions,theme,font-size); a whole-section id (appearance,cli-control— opens that page with no specific row; it is read in any case and with spaces, soSMSandAgent Emailreach thesmsandagent-emailpages instead of a same-named control on another page); the setting's AppSettings key in camelCase (gitGuardrailsReadyTagGateEnabled,sharesOpenInApp) — the same keyPATCH /settings/:keyandGET /settingsspeak, and the only name for a setting an AI is ever handed; or a fuzzy phrase (dark mode,sidebar position) resolved through the same catalog + search engine the Settings search box uses, so it lands exactly where typing the phrase would. A confident hit (the phrase is a setting's label, or the only result) scrolls to + flashes that row; an ambiguous phrase opens the best-guess section page without flashing a row, so a loose guess never highlights the wrong setting. A key that doesn't exist is split at its camelCase humps and retried as words, so you get a "did you mean…?" naming the nearest real settings rather than a dead end. A query that matches nothing at all opens Settings (last-viewed section) and shows a toast — never a blank or wrong landing. It's non-destructive (it only navigates — it never changes a setting), so it isn't approval-gated. This is the route an Omniscio agent uses to point you at a toggle it mentioned in chat.Open a Super Prompt.
omniscio://superprompt/<id>— opens the Super Prompts picker on that specific prompt (from a Copy-link button or an agent-emitted link). Following an external link only lands on the picker (confirmation-gated) — it never auto-runs the prompt; "Run it now" stays a separate in-app gesture.Open an Arij route.
omniscio://arij/<path...>(optionally?jql=…) — opens the Arij area on a specific route, e.g.omniscio://arij/browse/ARIJ-123oromniscio://arij/projects/ARIJ/board. The whole remainder (path + query) is handed opaque to Arij's own router, which resolves it.Ollert links. Three sub-routes under the
trellohost activate the Ollert panel and navigate its in-memory router:omniscio://trello/invite/<token>— open an invitation (used by the "Open in Omniscio" button on theamcback.jls.dev/invite/<token>landing page)omniscio://trello/board/<boardId>— jump directly to a boardomniscio://trello/card/<boardId>/<cardId>— jump directly to a card (the card modal over its board). TheboardIdandcardIdare percent-encoded in the URL and decoded by the parser.
Mission Control links. Sub-routes under the
mission-controlhost (the oldermondayhost is still accepted):omniscio://mission-control/join/<kind>/<token>— accept a shared board / workspace / dashboard (<kind>isboard,workspace, ordashboard)omniscio://mission-control/invite/<token>— complete a member invitation. Tokens are percent-encoded and decoded by the parser.omniscio://mission-control/board/<boardId>[?item=<itemId>]— open a Mission Control board directly. Activates the MC panel, navigates its internal router to/board/<boardId>. The optional?item=query param focuses a specific item/card on the board.omniscio://mission-control/board/<boardId>/view/<viewId>— open a board on one of its saved views.omniscio://mission-control/board/<boardId>/sprint/<sprintId>— open a board with that sprint selected in its sprint filter. A sprint that is not on that board opens the whole board instead of an empty one.omniscio://mission-control/dashboard/<dashboardId>— open a Mission Control dashboard.omniscio://mission-control/<goal|portfolio|document|spreadsheet|form>/<id>— open that goal, portfolio, document, spreadsheet or form page.omniscio://mission-control/people— open Mission Control on its People page (working hours, overloaded limits and the Team workload panel). It takes no id;people/<anything>is refused.
Every Mission Control link the app builds — the Copy link buttons on a board item, and the
deepLinkfield the/pmcreate and get routes for goals, portfolios, documents, spreadsheets, forms, sprints, boards and dashboards return — carries this instance's own scheme, so a link copied on a dev or sandbox instance opens that instance.GET /deep-link/resolvechecks a Mission Control link against the boards and workspaces the signed-in user can see: a made-up or deleted board, goal, item, view or sprint answers not found, and a teammate's board you are not a member of answers exactly the same way, so the check never reveals that it exists. A dashboard lives only in the cloud, so its link is never reported broken. A wrongly shaped Mission Control link is answered with the list of valid shapes.Link to a team chat message.
omniscio://chat/<kind>/<workspaceId>/<channelId>?message=<messageId>— where<kind>isorg(company workspace) orworkspace(self-serve workspace). Omniscio activates Team Chat, switches to that workspace and channel, and navigates to the message. The?message=anchor is optional — omitting it produces a channel-level link. Every message's hover toolbar has a share icon (and the mobile long-press action sheet has a "Copy link" row) that copies this link to your clipboard, Discord-style.Open a Supermail email thread.
omniscio://supermail/thread/<threadId>— activates the Supermail panel, forces its Mail view, and opens that email thread (<threadId>is Supermail's thread id, percent-decoded by the parser). It reuses the exact open path a Supermail notification click and the "Find Email" quick-launch already use, so a cold click still lands once the panel hydrates. It's non-destructive (reads, never sends), so it isn't approval-gated. Note the siblingomniscio://supermail/authlink is not this route — that's the OAuth sign-in callback, handled in the main process and never routed as a navigation.Open a calendar event.
omniscio://calendar/event/<eventId>?calendar=<calendarId>— activates the Calendar panel and pops up that event's details (the event popover). The Today's Agenda and "starting soon" reminder cards carry it on each event, beside a small Google link that opens the same event in the browser. An event outside the days the panel has loaded is fetched by id first (the optionalcalendarquery names the calendar it lives on, so a shared calendar's event is found). A deleted, cancelled or unreachable event shows a message instead of an empty panel, and with Calendar switched off the link says so. It only shows the event, so it isn't approval-gated. Rules:calendar-event-deep-link-contract.md.Open Tasks on a task, a project or a view.
omniscio://tasks/<taskId>opens Tasks and scrolls to that one task.omniscio://tasks/list/<listId>opens that project, andomniscio://tasks/view/<view>opens a view —all(All Projects),today,caught,archived,plan-my-day(starts the Plan my day session and opens its chat),closeout(the evening close-out) orcheckin(the Daily check-in thread). Each runs the same store call the matching rail row, menu item or button runs, so a link and a click land in the same place. An agent reaches the same places withPOST /tasks-v2/show({ taskId },{ listId }or{ view }), which rides the agent navigation guard: you get a click-to-go toast unless you allowed direct navigation. All navigate-only, exceptplan-my-day, which starts a session (asking to turn Plan my day on first while it is off).Spotlight a control after navigating. Append
?highlight=<anchor>[&highlightTitle=<title>&highlightMessage=<message>]to any navigate-only deep link — inbox, inbox alert, project, session, note, setting, mind-map, Arij, Ollert, Mission Control, team-chat, Supermail thread, or calendar event. After the target view mounts, Omniscio spotlights the element carryingdata-ui-anchor="<anchor>"using the same glass-tooltip overlay asPOST /ui/highlight. Example:omniscio://setting/cli-control?highlight=cli-control-regenerateopens CLI Control settings and rings the Regenerate button. Notes and constraints:- Navigate-only — the
?highlight=query is silently ignored on spawn (/new) and any other non-navigation path, because those paths don't land on a stable renderable view. Usesession/<id>?message=<msgId>(no?highlight=) to scroll to a specific chat message; a message inside the conversation scroller can't be spotlighted (the scroll engines would conflict). - Always on — the
deep-target-highlightfeature is released (statusshipped), so there is no switch: every navigate-only link that carries a valid?highlight=draws the spotlight. - Anchor charset —
<anchor>must be lowercase alphanumeric + hyphens only (the same names listed inGET /ui/snapshot). An invalid charset is ignored rather than erroring, matching the principle of graceful degradation for shareable links. - Same agent-nav guard — if the link is emitted by an agent session, the click-to-go toast shows the spotlight spec and replays it when the user clicks through, so the highlight still fires after a human-controlled navigation. The agent never forces the view change.
- Navigate-only — the
Open an automation rule.
omniscio://automation/<ruleId>— activates the Automations panel on that rule and expands it. A rule that is still waiting for approval opens its approval pane instead, because that is the surface carrying Approve and Reject (the rule editor cannot arm it): a rule an agent wrote through the CLI landspending, and this is the link that reaches the decision.POST /automation/rulesreturns it asapprovalUrlon a create or re-pend that lands pending, so the creating agent never has to guess a URL. With Automations switched off the link says so instead of navigating nowhere. Navigate-only.Open a scheduled job.
omniscio://cron/job/<jobId>— activates the Cron Jobs panel with that job selected, which is where Approve / Reject sit for a job parkedpending; on a phone it advances to the job'scron-detailroute.POST /cron/jobsandPATCH /cron/jobs/:idreturn it asapprovalUrlwhenever the saved job is pending. A job that is not on this computer says exactly that ("isn't on this computer") rather than claiming it was deleted — a synced schedule can be absent locally while alive elsewhere. Navigate-only.Open an audit run's report.
omniscio://nighty-tidy/run/<runId>— opens the Nighty Tidy panel on that run's app-built report. The Nighty Tidy batch card links each of its runs this way. Navigate-only.Open guided steps.
omniscio://settings-guide/<id>— opens the guided steps window, the right-hand column an agent's by-hand steps live in, beside whatever screen you are on, and moves to the first unfinished step's own place. It is the link inside an agent's Give me guided steps option (pressing Send on that option opens it too). It carries only the id, so nothing outside the app can put words in the window, and opening the same id again keeps your ticks. It only navigates, so it isn't approval-gated. If the steps are older than 7 days or have been dropped, you get "These guided steps have expired" and Settings opens. See settings-guided-steps.md.Open one Smrzz summary.
omniscio://smrzz/<summaryId>opens Smrzz on that summary. It is what a tap on a Smrzz "Summary ready" phone notice lands on. Navigate-only; a missing id, an extra segment, a control character or an id over 200 characters is refused.Wire it up anywhere. On Windows, any shortcut pointing at a URL that starts with
omniscio://(or the still-acceptedagentmc://) works. On macOS, Chrome/Safari will prompt the first time you click a link then remember. AutoHotkey:Run omniscio://inbox. PowerShell:Start-Process omniscio://inbox.
When an agent writes a broken link
Omniscio checks the omniscio:// links an agent hands you, and when one provably points at nothing
it fixes it in place, without involving you.
Two kinds of link count as broken. One points at something that does not exist. The other is a plain
link to the session you are already reading — it exists, but clicking it takes you nowhere, so
the agent is told the same way, and the agent's own link check (GET /deep-link/resolve) answers
"this is your own session" instead of "fine". A link to a specific message in that same thread
(?message= or ?turn=) still counts as useful. Every agent's instructions also say never to link
you to its own session.
A link wrapped in bold or italics (**omniscio://…**) is clickable, and the stars are never read as
part of the address. Before 2026-11-15 a bold link stayed plain text, was misread as a dead link
ending in **, and the in-place repair then deleted the closing ** — leaving literal asterisks in
your message.
What you see: nothing. What happens underneath is a short exchange you are never shown. Omniscio
tells that agent its link will not open and asks for a machine-readable correction — one marker line
([[OMNISCIO_LINK_FIX]]) followed by dead-link -> working-link, one per link. When the answer
comes back, Omniscio verifies each replacement actually resolves, rewrites the link inside the
original message, and pushes the corrected text straight to whatever you are looking at, phone
included. The request and the answer are both hidden from the thread, and your session goes back to
the state it was in, so no new card lands in your inbox. Your original message just becomes right.
Before this, the agent was asked to "send the corrected link", so it wrote you a whole second message while the first one still carried the dead link — you had to read both and mentally discard one.
Three things it deliberately will not do. It never swaps in a replacement that is itself dead (the new link is existence-checked first; a link it cannot check — say the app is running headless — is allowed through, matching how every other deep-link check treats an undecidable answer). It never hides a real message: the correction is recognised only when the agent's entire visible reply IS the payload, so an agent that has no working replacement just answers you in plain English and you read that normally. And if it turns out no message actually contains the link the agent named, it un-hides the reply rather than leaving you with nothing — a silent failure would be worse than a visible one.
Invariants: deep-link-existence-contract.md.
On mobile (the web-access app)
Deep links work on the phone too — with one unavoidable twist: a phone browser can't open a raw omniscio:// link (no mobile OS registers a desktop custom scheme, and a web app can't claim one), so on mobile the same links route two ways.
Links inside the app (the ones an agent writes in chat, search results, alerts, Copy-link buttons) are rendered by CopyableLink as click handlers, not raw <a href="omniscio://…">. Session / setting / mind-map / draft / share links already route through pure store navigation, so they worked on mobile from the start. Every other route (project, inbox, note, chat, page, Ollert, Mission Control, Supermail thread, Arij) used to round-trip through openAppLink → DEEP_LINK_OPEN, which is in the web-access WS BLOCKED_CHANNELS (it emits a DEEP_LINK_ACTION push that drives the desktop window, and that push is not forwarded to web clients) — so on a paired phone the tap did nothing. Now openAppLink is platform-aware: on the web (isBrowser) it calls the new read-only DEEP_LINK_RESOLVE invoke (parse-only via parseDeepLinkUrl — no push, no navigation, no entity lookup, so it is safe over the WS bridge and is baselined + resolve-adjudicated), then dispatches the returned action through the same routeDeepLinkAction the desktop push feeds, via a module-level handle useDeepLinkListener registers on mount (deep-link-dispatch-handle.ts). The desktop path is unchanged. See open-app-link.ts.
Links tapped from outside the app (an email, a text, a bookmark, a web-push notification) must be an HTTPS URL on your web-access origin carrying the target: https://<your-web-host>/#to=<url-encoded omniscio:// link>. The target rides in the URL fragment (#to=) — like the #auto= pairing token, the fragment is never sent to the server and never lands in an access log; a ?to= query is accepted as a redirect-safe fallback. On boot the renderer read-and-clears that target (boot-deep-link.ts) and routes it through the same DEEP_LINK_RESOLVE + routeDeepLinkAction path an in-app tap uses — the mobile analog of the desktop cold-start argv pull. If the phone isn't signed in yet (stale cookie or a fresh device), the login page carries the #to= fragment across sign-in (same-origin only; the token stays in #auto=) so it still lands. This also fixes web-push notification cold-taps: the legacy /?session=<id> push payload was ignored at boot and now routes. Build the HTTPS form with buildMobileDeepLink(origin, appLinkUrl) (build-mobile-deep-link.ts) — no token is embedded, so the link is a safe "open this on my phone" pointer, not a capability URL.
A "start a session" link does nothing on the phone. On the desktop, a project/<name>/new link always raises the spawn approval card first. The phone cannot raise that card yet, so DEEP_LINK_RESOLVE answers null for a new-session link, and neither an in-app tap nor an outside #to= link can start a paid session with a hidden prompt.
Safety invariants: a boot / login target is always re-parsed through the canonical parseDeepLinkUrl and only ever becomes an internal DeepLinkAction — a non-app-link target (e.g. #to=https://evil.com) is refused, so there is no open redirect and no raw-URL navigation; and no secret ever rides in a deep link (the pairing token stays in #auto=, the #to= target is a non-secret route id). Follow-up (not yet built): a one-click "Copy mobile link" affordance that surfaces buildMobileDeepLink in the UI. Not addressed: literal omniscio:// links tapped outside the app on a phone (that needs a native/installed app to claim the scheme).
Related
Deep Links (omniscio:// URLs) (part 2) — the continuation of this page. Deep links are one of two ways to drive Omniscio from outside — the other, which can also read a result back and is described on the CLI control page, goes over HTTP with a token. The panels most of these routes land on each have their own page: the note vault is covered by KMS, team messaging by Team Chat, and the email client by Supermail. Where a session link is rendered as a clickable result, that is the global search surface.
cli-control.md — CLI Control does the same things via HTTP (with a token) if you need the response to do something
GET /deep-link/resolve(CLI, bearer token) — dry-run anyomniscio://link and get back the action it resolves to, or a "did you mean" for a wrong guess, without navigating. For a setting link it goes further than checking the URL's shape: it looks the setting up in the live catalog, so a link naming a setting that doesn't exist comes back as a failure with the nearest real settings, instead of a green light that dead-ends when you click it. If no app window is open to check against, it says so rather than guessing either way. For an inbox card link it checks the card is really there; a link to an approval that has already been handled still answersok, plus anotesaying how it ended and when ("Already approved at Oct 12, 3:38 PM…") — the same thing the click shows — so an agent never hands it to you as something still to do. For a panel link —omniscio://session/<__sentinel__>, which is how a session link re-homes to a virtual project (Settings, PRD Studio, the shared-sessions hub, …) — it checks the id is one of the app's virtual projects, read from the one shared list rather than a copy, so a made-up or misspelled id (__prd-studio__for__prd_studio__) comes back as a failure naming the nearest real one instead of a green light that opens nothing. On a second copy of Omniscio (a named instance such as the experimental build, whose links areomniscio-<id>://), every message and suggestion names that copy's own scheme, and a plainomniscio://link is refused there because it belongs to the main copy. See cli-control.md.global-search.md — renders
omniscio://session/<id>as clickable internal linkskms.md — the KMS note vault;
omniscio://note/<path>opens a specific note in its panelteam-chat.md — the Team Chat feature;
omniscio://chat/<kind>/<wsId>/<channelId>opens a channel/messagesupermail.md — the Supermail email client;
omniscio://supermail/thread/<id>opens a specific email in its panel
Last verified 2026-10-31