Programmatic chat creation API for Codex Desktop: spawn a sidebar-visible chat with initial prompt from an external orchestrator

Thanks for the feature request.

It's unfortunate that codex exec doesn't work for this use case. That was going to be my initial suggestion, but you're correct that it produces sessions that are intentionally not enumerated by the app. We should think about ways to improve this.

In the meantime, another approach you could explore is using the app server interface. This is the same interface that the desktop app is built upon. It's a more complex interface than codex exec, but it's also way more flexible. You could ask Codex to write a small script that launches codex app-server and then uses its apis to create a new thread and inject a prompt.

This lines up closely with a workflow I’ve been trying to make reliable.

The app-server approach suggested above seems like the right direction for the “create a sidebar-visible chat + inject initial prompt” half of the problem. In my own setup, the adjacent problem is what happens after those lane chats exist: an orchestrator needs to keep those visible top-level chats addressable as durable worker lanes, instead of spawning disposable child sessions that disappear from normal operator workflows.

One useful observation from my local workflow: if I manually spend a few seconds creating the live sidebar chats first, the rest of the orchestration shape fits naturally. Once a normal sidebar-visible thread exists, it already has the right lifecycle, visibility, project scoping, and operator affordances. The missing piece is a supported way to attach that existing thread to an orchestrator as a routable subagent/lane.

I’ve been able to make that style of workflow work locally, but only by directly mutating local thread metadata / parent-child edge state. And reversing that mutation before any version updates. That proves the state shape is viable, but it’s obviously not something users should have to do directly.

I opened a narrower companion issue for that second half here:

https://github.com/openai/codex/issues/24398

And I put together a small reference branch showing one App Server-shaped way to expose it:

https://github.com/johnastinnett/codex/tree/codex/thread-attachments-rpc

That branch does not solve chat creation by itself. The connection I see is:

1. app-server creates a normal sidebar-visible thread and injects the initial prompt, or the user creates that thread manually in the Desktop app
2. app-server returns or is given the thread ID
3. an attachment RPC binds that existing thread to an orchestrator as a persistent, routable subagent/lane
4. the external orchestrator can then address the lane by thread ID without UI scripting or local state surgery

So I think this issue and #24398 are complementary: this issue covers programmatic thread creation, while #24398 covers durable orchestration over those created or manually prepared threads once they exist.

Working solution for programmatic sidebar thread creation

We ran into this exact problem and solved it — here's the key and a working implementation.

---

The key: ephemeral: false in thread/start

The app-server JSON-RPC protocol already supports persistent threads. The ephemeral field in thread/start defaults to true (disposable, not written to disk). Setting it to false persists the thread to ~/.codex/state_5.sqlite — the shared database the desktop app polls — and threads appear in the sidebar within seconds.

Implementation

We use a broker pattern: an app-server-broker.mjs daemon starts codex app-server as a subprocess and proxies JSON-RPC over a Unix socket. The client connects, creates a thread, sets its name, and fires off the initial turn:

\\\`javascript
// Create a persistent (non-ephemeral) thread
const { thread } = await client.request("thread/start", {
cwd,
approvalPolicy: "never",
sandbox: "workspace-write",
serviceName: "codex-fleet",
ephemeral: false, // ← persisted to state_5.sqlite → sidebar-visible
experimentalRawEvents: false,
});

// Set the sidebar display name (non-fatal on older CLI versions)
try {
await client.request("thread/name/set", { threadId: thread.id, name: "My Project Lane A" });
} catch {}

// Fire-and-forget the initial prompt — socket.end() flushes before FIN,
// so the broker receives turn/start even when the client closes immediately
client.request("turn/start", {
threadId: thread.id,
input: [{ type: "text", text: prompt, text_elements: [] }],
model: null,
effort: null,
outputSchema: null,
}).catch(() => {});
\\\`

Why fire-and-forget works

socket.write() is synchronous in the Node.js buffer. socket.end() flushes the buffer before sending FIN, so the broker subprocess receives the turn/start message even when the client closes immediately after. The agent runs independently in the broker subprocess; closing the client connection doesn't stop it.

Verification

We verified with a smoke test: all 3 threads (orchestrator + lane-a + lane-b) appeared in ~/.codex/session_index.jsonl within 3 seconds and showed sidebarVisibility: true. Threads created this way are indistinguishable from ones created interactively in the desktop app.

---

Hope this helps! This is the pattern we're using to auto-spawn multi-lane parallel Codex sessions directly into the sidebar without any manual copy-paste.

Clarification after deeper testing: the ephemeral: false mechanism above works for the VS Code extension context (threads written to ~/.codex/state_5.sqlite appear in the VS Code Codex sidebar). The standalone Codex desktop app appears to be cloud-backed — it stores/fetches threads from OpenAI's API and caches in its own Electron LevelDB (~/Library/Application Support/Codex/), and does not read from ~/.codex/state_5.sqlite. So programmatically-created threads via the broker approach show up in VS Code but not in the desktop app's sidebar.

If there's a way to target the desktop app's thread store (either a public API or a documented IPC protocol), we'd love to know — that would complete the picture.