›_ Codex Issues
Codex Issues / #29605

Codex Desktop: Deep links should support explicit window targeting

Open 💬 2 comments Opened Jun 23, 2026 by 0xdevalias

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.

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

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.

View original on GitHub ↗

2 Comments

0xdevalias · 2 months ago

One extra routing mode that would be useful here:

open this thread ID in an existing window if that exact thread is already open somewhere; otherwise open it in a new window

For example, a caller might want a stable "focus or create" behavior for:

codex://threads/<session-uuid>?window=existing-or-new

or whatever naming fits the eventual API shape.

That would be useful for external thread indexes, generated reports, scripts, bookmarks, and other tools that link back to known Codex threads. It avoids opening duplicate windows when the target thread is already visible, while still avoiding the more disruptive behavior of reusing an arbitrary existing Codex window that is showing a different thread.

There is a possible edge case where the same thread is already open in multiple Codex windows. In that case, focusing any window already showing the requested thread seems acceptable to me, since all of those windows refer to the same target thread. The important distinction is between "reuse a window that is already showing this thread" and "reuse some other existing Codex window and navigate it away from its current thread."

0xdevalias · 2 months ago

Another related mode that seems worth supporting explicitly: focus an existing Codex window for a given thread ID, if that thread is already open somewhere.

For example, a caller might want behavior like:

codex://threads/<session-uuid>?window=focus

or whatever naming fits the eventual API.

Semantically, this would mean: if any Codex window is already showing <session-uuid>, bring that window to the foreground without navigating another window away from its current thread. If the thread is not currently open in any window, this should probably be a no-op or documented error rather than falling back to opening/navigating a different window.

There is some prior art for this kind of explicit focus behavior:

This is slightly different from "open in a new window" or "reuse existing-or-new": sometimes external tooling wants to avoid creating or navigating anything and only bring the already-open target thread to the foreground if it exists.