stablyai / stablyai/orca

Clickable orca:// deep-links to focus a terminal/worktree

Open
#4,384 1 comment 4 reactions 1 assignee Claimed by @OrcaWin View on GitHub
enhancement size/m
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.