Show Codex sessions as normal desktop threads

Co-Authored-By: OpenAI Codex <noreply@openai.com>

Author: xuio

README.md

@@ -23,7 +23,7 @@ debugging, or adversarial review.
 - **No daemon:** Claude launches the MCP server over stdio for the active session.
 - **Fast parallel review:** Claude can launch several independent Codex agents with bounded concurrency.
 - **Persistent sessions:** App-server sessions keep Codex context across prompts and support live steering.
-- **Codex desktop friendly:** The plugin prefers the Codex binary shipped inside `Codex.app` when it exists.
+- **Codex desktop friendly:** The plugin prefers the Codex binary shipped inside `Codex.app` and creates normal Codex threads with task names for Desktop history.
 - **Debuggable:** Verbose JSONL logging, diagnostics bundles, progress events, per-session resources, and recovery hints are built in.
 
 ## Quick Start
@@ -120,6 +120,11 @@ to `codex://sessions/{session_id}` for milestone and completion updates. For a
 completed first turn, Claude should set `keep_session: true`; for long first
 turns, Claude should set `background: true`.
 
+When app-server sessions use the Codex desktop binary, they are recorded as
+normal top-level Codex threads rather than hidden daemon work. The plugin sets the
+thread name from Claude's task label when the installed Codex app-server supports
+thread naming.
+
 ## Safety Model
 
 The default execution mode is conservative:

dist/index.js

@@ -24113,6 +24113,11 @@ var LimitedText2 = class {
 function userText(text) {
   return { type: "text", text, text_elements: [] };
 }
+function desktopThreadName(name) {
+  const trimmed = name?.trim();
+  if (!trimmed) return void 0;
+  return trimmed.length > 120 ? `${trimmed.slice(0, 117)}...` : trimmed;
+}
 function sandboxPolicy(options) {
   if (options.dangerouslyBypassApprovalsAndSandbox) return { type: "dangerFullAccess" };
   switch (options.sandbox ?? "read-only") {
@@ -24330,14 +24335,16 @@ var CodexAppServerSession = class _CodexAppServerSession {
         sandbox: sandboxMode(options),
         config: appServerConfig(options, reasoningEffort),
         serviceName: "claude-code-codex-subagents",
-        ephemeral: options.ephemeral ?? false,
-        threadSource: "subagent"
+        ephemeral: options.ephemeral ?? false
       }, options.spawnTimeoutMs ?? 3e4);
       const threadId = thread.thread?.id;
       if (!threadId) throw new AppServerUnavailableError("Codex app-server did not return a thread id.");
       session.threadId = threadId;
       if (resumeThreadId) session.capabilities.threadResume = true;
       else session.capabilities.threadStart = true;
+      if (!resumeThreadId) {
+        await session.setThreadName(desktopThreadName(options.name), options.spawnTimeoutMs ?? 3e4);
+      }
       await session.probeThreadRead(options.spawnTimeoutMs ?? 3e4);
       return session;
     } catch (error2) {
@@ -24354,6 +24361,20 @@ var CodexAppServerSession = class _CodexAppServerSession {
     this.userAgent = typeof initialized?.userAgent === "string" ? initialized.userAgent : void 0;
     this.codexHome = typeof initialized?.codexHome === "string" ? initialized.codexHome : void 0;
   }
+  async setThreadName(name, timeoutMs) {
+    if (!name) return;
+    try {
+      await this.request("thread/name/set", { threadId: this.threadId, name }, timeoutMs);
+    } catch (error2) {
+      logger.warn("codex.app_server.thread_name_failed", {
+        ...this.logContext,
+        appServerId: this.id,
+        threadId: this.threadId,
+        name,
+        error: errorForLog(error2)
+      });
+    }
+  }
   get activeTurnId() {
     return this.activeTurn?.turnId;
   }

docs/ARCHITECTURE.md

@@ -30,6 +30,11 @@ flowchart LR
 The app-server process is a child of the MCP server. When Claude shuts down the
 MCP server, there is no background daemon left behind.
 
+App-server threads are started as normal top-level Codex threads, not as nested
+Codex subagent threads. When the Codex app-server supports `thread/name/set`, the
+plugin best-effort names the thread from Claude's task label so the run is easy
+to find in Codex Desktop history.
+
 ## Binary Resolution
 
 The resolver checks candidates in this order:

src/app-server.ts

@@ -32,6 +32,7 @@ type AppServerRequestMethod =
   | "initialize"
   | "thread/start"
   | "thread/resume"
+  | "thread/name/set"
   | "turn/start"
   | "turn/steer"
   | "turn/interrupt"
@@ -118,6 +119,12 @@ function userText(text: string): JsonObject {
   return { type: "text", text, text_elements: [] };
 }
 
+function desktopThreadName(name: string | undefined): string | undefined {
+  const trimmed = name?.trim();
+  if (!trimmed) return undefined;
+  return trimmed.length > 120 ? `${trimmed.slice(0, 117)}...` : trimmed;
+}
+
 function sandboxPolicy(options: AgentRunOptions): JsonObject {
   if (options.dangerouslyBypassApprovalsAndSandbox) return { type: "dangerFullAccess" };
   switch (options.sandbox ?? "read-only") {
@@ -347,13 +354,15 @@ export class CodexAppServerSession {
             config: appServerConfig(options, reasoningEffort),
             serviceName: "claude-code-codex-subagents",
             ephemeral: options.ephemeral ?? false,
-            threadSource: "subagent",
           }, options.spawnTimeoutMs ?? 30_000) as { thread?: { id?: string }; cwd?: string };
       const threadId = thread.thread?.id;
       if (!threadId) throw new AppServerUnavailableError("Codex app-server did not return a thread id.");
       session.threadId = threadId;
       if (resumeThreadId) session.capabilities.threadResume = true;
       else session.capabilities.threadStart = true;
+      if (!resumeThreadId) {
+        await session.setThreadName(desktopThreadName(options.name), options.spawnTimeoutMs ?? 30_000);
+      }
       await session.probeThreadRead(options.spawnTimeoutMs ?? 30_000);
       return session;
     } catch (error) {
@@ -372,6 +381,21 @@ export class CodexAppServerSession {
     this.codexHome = typeof initialized?.codexHome === "string" ? initialized.codexHome : undefined;
   }
 
+  private async setThreadName(name: string | undefined, timeoutMs: number): Promise<void> {
+    if (!name) return;
+    try {
+      await this.request("thread/name/set", { threadId: this.threadId, name }, timeoutMs);
+    } catch (error) {
+      logger.warn("codex.app_server.thread_name_failed", {
+        ...this.logContext,
+        appServerId: this.id,
+        threadId: this.threadId,
+        name,
+        error: errorForLog(error),
+      });
+    }
+  }
+
   get activeTurnId(): string | undefined {
     return this.activeTurn?.turnId;
   }

test/fixtures/fake-codex.mjs

@@ -58,6 +58,7 @@ if (args[0] === "app-server") {
   let activeTurn = undefined;
   let activePrompt = "";
   let activeSteers = [];
+  let threadName = null;
   let activeTimer = undefined;
 
   function modeText() {
@@ -215,6 +216,15 @@ if (args[0] === "app-server") {
         return;
       }
       threadId = `fake-thread-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
+      threadName = null;
+      recordCall({
+        protocol: "app-server",
+        method,
+        threadId,
+        cwd: params?.cwd ?? process.cwd(),
+        threadSource: params?.threadSource ?? null,
+        serviceName: params?.serviceName ?? null,
+      });
       if (hasMode("THREAD_START_NO_ID")) {
         send({ id, result: { thread: {}, cwd: params?.cwd ?? process.cwd() } });
         return;
@@ -240,7 +250,7 @@ if (args[0] === "app-server") {
             agentNickname: null,
             agentRole: null,
             gitInfo: null,
-            name: null,
+            name: threadName,
             turns: [],
           },
           model: params?.model ?? "fake-model",
@@ -257,6 +267,16 @@ if (args[0] === "app-server") {
       send({ method: "thread/started", params: { thread: { id: threadId, cwd: params?.cwd ?? process.cwd(), turns: [] } } });
       return;
     }
+    if (method === "thread/name/set") {
+      threadName = typeof params?.name === "string" ? params.name : null;
+      recordCall({ protocol: "app-server", method, threadId: params?.threadId ?? threadId, name: threadName });
+      if (hasMode("THREAD_NAME_SET_ERROR")) {
+        send({ id, error: { code: -32000, message: "fake thread name set error" } });
+        return;
+      }
+      send({ id, result: {} });
+      return;
+    }
     if (method === "thread/resume") {
       if (hasMode("THREAD_RESUME_ERROR")) {
         send({ id, error: { code: -32000, message: "fake thread resume error" } });
@@ -441,7 +461,7 @@ if (args[0] === "app-server") {
         send({ id, error: { code: -32000, message: "fake thread read error" } });
         return;
       }
-      send({ id, result: { thread: { id: threadId, turns: [] } } });
+      send({ id, result: { thread: { id: threadId, name: threadName, turns: [] } } });
       return;
     }
     send({ id, error: { code: -32601, message: `unknown method ${method}` } });

test/sessions.test.ts

@@ -80,6 +80,32 @@ describe("CodexSessionManager", () => {
     manager.cancel(started.session.id);
   });
 
+  it("starts app-server sessions as normal desktop-visible Codex threads with task names", async () => {
+    const manager = new CodexSessionManager();
+    const projectDir = await tempDir("codex-subagents-session-project-");
+    const recordDir = await tempDir("codex-subagents-session-record-");
+
+    const started = await manager.start({
+      prompt: "desktop visible session",
+      name: "Review desktop visibility",
+      projectDir,
+      codexBin: fakeCodex,
+      env: {
+        FAKE_CODEX_RECORD_DIR: recordDir,
+      },
+    });
+
+    expect(started.result.ok).toBe(true);
+    const calls = await recordedCalls(recordDir);
+    const threadStart = calls.find((call) => call.method === "thread/start");
+    expect(threadStart?.threadSource).toBeNull();
+    expect(threadStart?.serviceName).toBe("claude-code-codex-subagents");
+    expect(calls.some((call) => call.method === "thread/name/set" && call.name === "Review desktop visibility")).toBe(
+      true,
+    );
+    manager.cancel(started.session.id);
+  });
+
   it("delivers steering to the active app-server turn", async () => {
     const manager = new CodexSessionManager();
     const projectDir = await tempDir("codex-subagents-session-project-");
@@ -110,7 +136,10 @@ describe("CodexSessionManager", () => {
     expect(waited.session?.lastResult?.finalMessage).toContain("steer this active turn");
 
     const calls = await recordedCalls(recordDir);
-    expect(calls.map((call) => call.method).filter((method) => method !== "thread/read")).toEqual(["turn/start", "turn/steer"]);
+    expect(calls.map((call) => call.method).filter((method) => method === "turn/start" || method === "turn/steer")).toEqual([
+      "turn/start",
+      "turn/steer",
+    ]);
     manager.cancel(session.id);
   });