Repository navigation
feat(desktop): kirocrew:// URL scheme and kirocrew open to reach a session - #23197
Conversation
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level blocker. The URL allowlist is rebuilt from parsed parts, delivery reuses Notes
[DESIGN-REVIEWED] e1d3b65 Description read[DESCRIPTION-READ] 7fbb9000442ecb0888e41f72950b714399425e17078b33520d1471c9e63c18e3 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
UX Review (Opus 5.5, fork) — ⏭️ skippedRevision |
69bcb5b to
1f24b66
Compare
First Principles Review (Opus 5.5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. Two notes: the PR claims the scheme in Nightly too, which the base records as unable to tell the two apps apart, and it ships an undeclared Remote Crew pane switch. Notes
What this change shipsInventory (8 items) — 6 justifiedIntent: let another program on the machine open the desktop app on a given session with one URL. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] e1d3b65 Description read[DESCRIPTION-READ] d5bdc5c6ead83e13ae2aa1c5de0063fd2f68b69988451160d2970b937e4f246d That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
1f24b66 to
a5c9b89
Compare
|
|
|
|
|
|
|
|
|
|
|
a5c9b89 to
23c33d2
Compare
|
|
|
|
|
|
|
|
|
|
23c33d2 to
5e67b10
Compare
The installer registers `kirocrew://` on macOS, Windows and Linux. Two link shapes are accepted: a bare `kirocrew://` raises the window, and `kirocrew://chat?sid=<slot key>` opens that session. Links are parsed and allowlisted in a pure module, delivered through the Crew Companion's existing origin-matched readiness check, and held until the dashboard document has mounted its `navigate` listener (the renderer acks with `navigate-ready`; a new main-frame navigation re-arms the wait). The launching process's own argv is read once, so a cold start on Windows or Linux opens the session too.
Builds `kirocrew://chat?sid=<key>` (or the bare scheme with no session) with the same slot-key grammar the Electron resolver accepts, pinned by a cross-language test, and hands it to the OS through `platform_compat_trust.open_with_default_app` on macOS and Linux and `os.startfile` on Windows. The shared launcher gains an optional `wait_for_exit` so the CLI can report "no application is registered" from `open` / `xdg-open`'s exit status instead of exiting 0; other callers keep the fire-and-forget default. `--print` writes the URL instead of opening it.
5e67b10 to
e1d3b65
Compare
|
|
Hold at e1d3b65 for human review. Reserved for a human. This registers a Also open on this head:
AI findings judged non-blocking
Checks are green and there is no conflict with main. — crew-pr-reviewer (r133) |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved on behalf of the watch holder (bolichen). Design and First Principles pass on this head (or skipped / author override), UX skipped or pass, no conflict, no open change request.
|
I feel that this task is only 50% done:
I see no user friendly way to grab the new URL?
|

Problem / Motivation
Goal: Another program on the machine can open the KiroCrew desktop app on a specific session with one URL,
kirocrew://chat?sid=<key>.Nothing outside the desktop app can tell it which session to show. The dashboard's
/chat?sid=link works in a browser tab;open -a KiroCrewonly raises the window; the one in-app route (the Crew Companion overlay's "Open session", anavigateIPC) is reachable from inside the Electron process alone. A companion app that posts to a session through/api/chatand wants to hand the user back to it ends up opening a browser tab beside the running desktop app, so the same session is open twice.Why it matters
Every "open this in Kiro Crew" affordance outside the app wants this: a menu-bar quick-ask panel, a Slack button, a Raycast or Alfred action, a script. Without a scheme each one is stuck with the browser link, which puts the user in a second copy of the dashboard rather than the app they already have open.
Not a goal
/chat?sid=<key>are accepted; adding a route is a deliberate allowlist change.second-instancewith no link) does.What changed (motivation → approach → change)
A
kirocrew://URL is text another program chose, so the shell treats it as untrusted: it parses the URL, accepts exactly two shapes (bare, andchat?sid=<key>with a conservative key grammar), and rebuilds the route from the parsed parts instead of copying the input. Delivery reuses the Crew Companion's origin check (hostsDashboard), so there is one definition of "the dashboard is loaded";openSettingsPageis untouched.A link can arrive before the dashboard can take it. The renderer tells the main process when its
navigatelistener exists (navigate-ready, sent once per document by the preload), and the handler holds at most one link until that ack; a new main-frame navigation re-arms the wait. The launching process's own argv is read once after the handler is installed, which is how a cold start on Windows or Linux reaches the session (macOS gets the URL throughopen-url).website/electron/package.jsonbuild.protocolsdeclareskirocrew; the two new modules are packagedwebsite/electron/deep-link.jsresolveDeepLink(parse + allowlist),deepLinkFromArgv(pick the URL off a Windows/Linux argv); no Electron importwebsite/electron/deep-link-handler.jsinstallDeepLinks(setAsDefaultProtocolClient, failure logged and degraded, skipped in a dev run of the stock electron binary so it cannot overwrite the installer's registration;open-urlon macOS);installNavigateReady(the ack and re-arm wiring)website/electron/main.js,preload.js,crew-companion/index.jsdeliverDeepLinkraises the main window and sendsnavigatethroughhostsDashboard(wc, base), which gains an optional base so it answers before the companion initialises; the preload sendsnavigate-readysrc/kiro_crew/cli_open.py,cli_parser_gateway.py,cli_help.py,cli.py,platform_compat_trust.pykirocrew open [SESSION] [--print]builds the URL with the same key grammar (fullmatch, so a trailing newline is refused like the JS side) and hands it toplatform_compat_trust.open_with_default_app(macOS/Linux) oros.startfile(Windows). The shared launcher gains an optionalwait_for_exit; the CLI uses it soopen/xdg-openexiting non-zero (no application registered) is reported as a failure with the browser fallback named, instead of exit 0.--printwrites the URL instead; the parser, help row and dispatch register the verbdocs/system-specs/modules/cli.mdkirocrew openrowBackwards compatibility
Compatible: nothing main accepts today is rejected, renamed or removed. A plain
second-instancestill callsshowMainWindow({ focus: true });openSettingsPageandopenDashboardSessionkeep their signature and behaviour;hostsDashboard's new parameter defaults to the value it read before, andopen_with_default_app's new keyword defaults to today's fire-and-forget behaviour for every existing caller. New files, a newprotocolskey, one new CLI subcommand, one new renderer-to-main IPC message (navigate-ready) that nothing else listens for.Removes nothing.
Tests
website/electron/test/deep-link.test.js: each accepted form and its exact route; the sid is re-encoded rather than copied; refusal shapes each with their reason (wrong scheme, credentials, port, fragment,settings/artifacts/unknown hosts, extra path segments, every non-sidquery parameter, missing/empty/over-long/space/leading-dash/HTML-shaped sid); dot-segment normalisation stays inside the route;deepLinkFromArgvpicks the last URL and answers "" for a macOS argv;package.json build.protocolsnames the scheme the resolver accepts.website/electron/test/deep-link-handler.test.js: registration runs in a packaged app and is skipped (and logged) underprocess.defaultApp; a link before the ack is held; the ack flushes it exactly once; a later link replaces a held one; a bare link raises immediately; a new main-frame navigation re-arms the wait;navigate-readycounts only from the dashboard view; a cold-start argv link is held until the ack; a refused URL opens nothing and the log names the reason, not the payload;open-urlonly on darwin; main.js reads the launching argv once right after installing the handler and routessecond-instancethrough it with the previous fallback.website/electron/test/preload-navigate-ready.test.js: the ack is sent after the listener registers, once per document, and again for a fresh document.website/electron/crew-companion/test/petOverlay.test.js:hostsDashboardanswers with an explicit base before init; default behaviour unchanged.test/test_reveal_in_file_manager.py:open_with_default_appnever waits by default; withwait_for_exit, exit 0 is True, exit 1 or 3 is False, a still-running launcher is True, a missing launcher spawns nothing.test/test_cli_open.py: URL building for a session and the bare case; refusals match the desktop resolver, including a trailing newline; macOS/Linux go through the shared launcher withwait_for_exit, a non-zero launcher exit is reported as "no application is registered", and Windows goes throughos.startfile(mocked, nothing launched); CLI wiring through--print, exit 2 with a reason on a bad key, exit 1 naming the fallback when the OS cannot open; a pin that the Python slot-key pattern and scheme are byte-identical todeep-link.js.website/electronnpm test2833 pass / 0 fail;pytest test/test_cli_open.py test/test_cli_help.py test/test_reveal_in_file_manager.py50 pass;test/test_flake_pattern_ratchet.py60 pass; isort, flake8, the black gate, mypy (--platform linux) and the brand gate clean.Manual verification
Needs a packaged build:
setAsDefaultProtocolClientis a no-op for an unbundled Electron, so the scheme can only be exercised end to end from a built.app/ installer. Planned on the macOS artifact once CI produces one: (1)open "kirocrew://chat?sid=<an open slot>"with the app running lands on that session; (2) the same with the app quit launches it and lands on the session once the dashboard has mounted (held-link path); (3)open "kirocrew://chat?sid=a%20b"andopen "kirocrew://evil"are refused with a log line and the window is untouched; (4) a plain relaunch still only raises the window. The Windows/Linux cold-start argv path is covered by unit tests; I cannot run the packaged binaries there.Screenshots / video
Why no screenshot: no rendered surface changes; the dashboard is navigated to a page that already exists, and the only new user-visible text is the
kirocrew open --helpoutput.Related Issues
Closes #23195