Clickable orca:// deep-links to focus a terminal/worktree
- Dominant language
- TypeScript
- Stars
- 72.1k
- Forks
- 4.7k
- Avg merge
- 14h 54m
- Merged PRs (30d)
- 520
Description
## Summary
There is no way today to emit a clickable string that focuses a specific Orca terminal tab. Orca registers **no OS URL scheme** — `Info.plist` has no `CFBundleURLTypes`, the main process never calls `setAsDefaultProtocolClient`, and `handleOscLink` only routes `http`/`https`/`file`. The existing `orca://pair` flow is handled purely in the **web** renderer via `location.hash` (web-pairing), not as an OS deep-link, so it doesn't help here.
The clickable system-notification path works only via an in-app `Notification` `click` handler — it can't be embedded in terminal/chat text. Borja wants to **click a link in the terminal and have Orca jump to that tab** — explicitly **no notifications**.
## Goal
Clickable, in-terminal links that focus a specific Orca terminal tab when clicked:
```
orca://focus/
```
(`` is the runtime-issued handle from `orca terminal list --json`, e.g. `term_`.)
## Plan
1. **Register the `orca://` URL scheme** so the OS routes `orca://…` to the app:
- `app.setAsDefaultProtocolClient('orca')` in the main process (with the `process.defaultApp` dev-exe variant for Windows/Linux).
- `protocols` entry in `config/electron-builder.config.cjs` → electron-builder injects `CFBundleURLTypes` (macOS) / NSIS scheme (Windows).
- Route deep-links via `app.on('open-url')` (macOS) and `second-instance` / initial `process.argv` (Windows/Linux).
2. **Handler** — `orca://focus/` brings that tab/pane to the foreground by **reusing the existing canonical action** behind `terminal switch` / `terminal focus` and the notification-click handler: `runtime.focusTerminal(handle)` → `ui:focusTerminal` → `activateTabAndFocusPane`. No new focus logic.
3. **Linkification in the embedded terminal (primary surface)** — emit **OSC 8 hyperlinks** so the text is clickable. Orca's xterm `linkHandler` already sets `allowNonHttpProtocols: true` and routes clicks to `handleOscLink`; we add an `orca:` branch there that forwards the deep-link to the same main-process router (Cmd/Ctrl+click, consistent with existing http/file links).
## Feasibility note — the "Claude Code chat surface"
In Orca, Claude Code (and every agent) runs **inside the xterm terminal** — there is no separate React-rendered markdown chat surface for it; the chat *is* the terminal. So the delivery vehicle is OSC 8 hyperlinks (which is exactly how markdown links like `[label](orca://focus/term_…)` are rendered into a terminal). Plain-text `orca://…` will **not** auto-linkify (xterm's `WebLinksAddon` only autodetects http/https); the link must be emitted as an OSC 8 hyperlink. This is an accepted, documented limitation.
## Out of scope (deferred)
- No notifications.
- `orca://worktree/` is deferred — worktree ids are `repoId::worktreePath` and need URL-encoding; the focus-by-handle case fully delivers the goal.
Implementation will land as a separate, minimal-surface PR.
Contributor guide
Assessment
This issue has not been assessed yet.