Codex Desktop: Deep links should support explicit window targeting

Summary

Codex Desktop supports codex:// deep links / URLs for opening existing local threads and starting new threads. These protocol URLs are useful from scripts, local indexes, browser bookmarks, generated reports, and external tooling.

However, there does not appear to be a documented way for a deep-link caller to control where the target opens: for example, whether it should reuse an existing Codex window or open in a new independent Codex window.

Please add a documented, stable window-targeting option for Codex Desktop deep links.

Problem

Codex Desktop supports multi-window workflows, which are especially useful when supervising multiple threads, projects, or agents across different workspaces or macOS Spaces.

Deep links / protocol URLs are a natural way to navigate into Codex from outside the app, but today they appear to leave window selection up to Codex Desktop. For example:

codex://threads/<session-uuid>

opens an existing local thread, but appears to reuse an existing Codex window when one is available. That can disrupt whichever window Codex chooses to reuse.

This is most obvious for existing thread links, but the same general capability may be useful for other deep-link targets where opening in a new window makes sense, such as:

codex://threads/<session-uuid>
codex://threads/new
codex://threads/new?prompt=...&path=...
codex://new?prompt=...&path=...

The request is not to change the default behavior of existing links. It is to add an explicit, documented option that callers can opt into when they need predictable window behavior.

Expected behavior

Codex Desktop should provide a documented way for supported deep links to request opening their target in a new independent window.

The exact API shape is up to the maintainers, but examples could be:

codex://threads/<session-uuid>?window=new
codex://threads/<session-uuid>?newWindow=true
codex://threads/new?window=new

or another officially supported route/query parameter.

Ideally, this would be handled consistently across deep-link families where window targeting makes sense.

Actual behavior

Supported codex:// links open their target, but I could not find a documented query parameter or route that asks Codex Desktop to open the target in a new independent window.

For existing local thread links specifically, codex://threads/<session-uuid> appears to reuse an existing Codex Desktop window when one is available.

Reproduction steps

1. Open Codex Desktop.
2. Open or create a local thread.
3. From outside Codex, open a deep link such as:

``text
codex://threads/<session-uuid>
``

1. Observe that Codex opens the target by reusing an existing Codex window.
2. Try to force the target to open in a new independent Codex window.
3. Observe that there does not appear to be a documented deep-link option for this.

Desired acceptance criteria

• There is a documented way for supported Codex Desktop deep links to request a new independent window.
• The behavior works for existing local thread links, not only new-thread links.
• Existing deep-link behavior remains backward compatible.
• The docs explain the window behavior clearly, including the difference between:
• opening in the current/reused window;
• opening in a new independent window;
• creating a brand-new thread, where relevant.
• Unsupported combinations are either ignored safely or documented clearly.

Prior art / API shape reference

Obsidian's URI scheme has a useful precedent here. Its paneType parameter controls where a target opens in the UI:

obsidian://open?vault=...&file=...&paneType=window

Obsidian documents related values for opening in a new tab, split, or desktop pop-out window. This request is not asking Codex to copy Obsidian's exact naming, but it is a good example of a documented deep-link parameter that lets callers choose the UI target.

Reference: https://obsidian.md/help/uri#Parameters

Adjacent context

#28677 is a separate request about terminal-launched context targeting or reusing an active thread. It is not the same issue, but it overlaps conceptually: both cases would benefit from Codex having a clearer model for caller-controlled targeting.

• https://github.com/openai/codex/issues/28677

In that discussion, I suggested that terminal/app handoff flows may need explicit destination controls rather than relying on implicit app state:

• https://github.com/openai/codex/issues/28677#issuecomment-4777951905

Deep-link window targeting is the same kind of problem at the URL/API layer: callers need a documented way to say where the target should open.