›_ Codex Issues
Codex Issues / #31417

Codex Desktop macOS: read_thread_terminal cannot see a working integrated terminal

Open 💬 4 comments Opened Jul 7, 2026 by jlecerf62

Summary

In Codex Desktop on macOS, the integrated terminal is open and fully functional, but the agent-side read_thread_terminal tool cannot read it and always returns:

No app terminal session is attached to this thread yet.

The desktop logs show that the visible route uses the permanent thread ID while panel/session ownership continues to use a temporary client-new-thread:... ID. This appears to prevent the terminal snapshot lookup from finding the current thread's terminal.

Environment

  • Codex Desktop: 26.623.141536 (build 4753)
  • Bundled Codex CLI: 0.142.5
  • macOS: 26.5.1 (25F80)
  • Architecture: Apple Silicon (arm64)
  • Authentication: ChatGPT
  • Thread type: local/projectless desktop thread

Actual behavior

  1. The integrated terminal opens inside the Codex app.
  2. Commands run normally. codex doctor --all reports that stdin, stdout, and stderr are TTYs, with TERM=xterm-256color, and correctly identifies the current project.
  3. Asking the agent to inspect the current terminal invokes read_thread_terminal.
  4. The tool responds that no app terminal session is attached.
  5. The same failure occurs with a second terminal tab.

Relevant sanitized desktop-log pattern:

conversationId=client-new-thread:<temporary-id>
ownerRoutePath=/local/<permanent-thread-id>

The IDs remain different after switching to another chat and returning.

Expected behavior

The terminal session visible in the current thread should be associated with the permanent thread ID, and read_thread_terminal should return the active integrated-terminal snapshot.

This is also the behavior described in the Codex app documentation: Codex can read the current integrated-terminal output.

Steps to reproduce

  1. Open Codex Desktop on macOS.
  2. Create a new local/projectless thread.
  3. Open the integrated terminal in that thread.
  4. Run:

``sh
printf 'codex-terminal-check\n'
``

  1. Ask the agent to read/check the built-in terminal.
  2. Observe:

``text
No app terminal session is attached to this thread yet.
``

Recovery attempts

  • Closed and reopened the terminal panel.
  • Created another terminal tab and selected it.
  • Switched to another chat and returned.
  • Quit and restarted Codex, then created a fresh terminal.
  • Confirmed the Codex installation, databases, configuration, authentication, network, and thread inventory pass codex doctor --all.

The issue persists.

Additional information

No raw logs or full thread identifiers are included here because they can contain private information. A sanitized log excerpt or an in-product /feedback session can be provided if needed.

View original on GitHub ↗

4 Comments

AliAltivate · 1 month ago

I traced the shipped Desktop renderer and found the concrete lookup mismatch described here. Terminal sessions are stored under clientThreadId, while read_thread_terminal initially queries by permanent thread ID. The renderer already maintains a permanent-ID → client-ID alias map; the minimal fix is alias-aware snapshot lookup rather than rekeying/restarting the PTY.

A related route bug also returns null for client-local-thread, causing the terminal toggle to silently no-op. Full findings, patch pseudocode, and regression cases are in: https://github.com/openai/codex/issues/28141#issuecomment-4953033965

I did not open a public PR because these Desktop renderer symbols are not present in the public repository; the public app-server PTY layer does not own Desktop route/session aliases.

Radagast011 · 1 month ago

Reproduced on a newer macOS Desktop build.

Environment

  • Codex Desktop: 26.707.72221 (build 5307)
  • Bundled Codex CLI: 0.144.2
  • macOS: 26.0.1
  • Architecture: Apple Silicon / arm64
  • Thread type: local folder-backed Desktop task

Observed behavior

  1. Open the integrated terminal in the active task.
  2. Run a sentinel command; the terminal is fully interactive and displays the expected output.
  3. Ask the agent to inspect the active terminal.
  4. read_thread_terminal consistently returns:
No app terminal session is attached to this thread yet.

The visible terminal remains usable throughout.

Recovery attempts

  • Closed and reopened the terminal panel.
  • Created and selected a new terminal tab.
  • Quit and restarted the Desktop app.
  • Reopened the task and created another terminal.

The failure persists.

Sanitized local inspection shows no shell or PTY startup failure. The behavior is consistent with the reported terminal-owner lookup mismatch: the visible terminal exists, but the snapshot lookup for the permanent thread ID resolves no attached session.

No raw logs, task identifiers, filesystem paths, hostnames, account details, network addresses, screenshots, or credentials are included here.

bjober · 22 days ago

I got the integration working thus recovering from this situation simply by choosing an avatar. I did not choose an avatar during installation.
I could then op-out of the annoying little bagger an still have the terminal connection working.

bitzam · 16 hours ago

Additional reproducible evidence on the current macOS build:

Environment

  • Codex Desktop: 26.820.60940 (build 7119)
  • Bundled Codex CLI/App Server: 0.150.0-alpha.8
  • macOS, Apple Silicon

Reproduction

  1. Quit and restart Codex, confirming that no PTYs remain.
  2. Start one agent-side interactive shell and retain its returned session ID.
  3. Call open_in_codex({ target: { type: "terminal", sessionId } }) for the currently visible thread.
  4. Write a unique marker to the retained agent-side session.
  5. Inspect the visible terminal and call read_thread_terminal.

Actual result

  • open_in_codex returns queued.
  • The agent-side shell remains on one PTY as a child of the Codex app server.
  • The desktop UI independently starts a new /bin/zsh on a different PTY as a child of the desktop app, with the same working directory.
  • The marker exists only in the agent-side PTY. The UI stays at a blank prompt, and read_thread_terminal returns that blank UI shell.
  • Reproduced 2/2 after a clean restart.
  • Explicitly navigating to the permanent current thread before retrying does not help; the queued action still creates a fresh UI shell.

Sanitized log sequence

  • The renderer reports the open_in_codex call as success=true.
  • Around the call, sidebar ownership is temporarily associated with client-new-thread:<temporary> / the home route and the permanent thread becomes inactive.
  • Several seconds later, ownership rebinds to the permanent thread.

This suggests the queued path may lose or replace the supplied sessionId, creating a fresh UI PTY instead of attaching the requested backend PTY. Returning success/queued also hides the mismatch.

Validated workaround
A shared terminal-multiplexer session joined by both the agent-side shell and the visible UI shell makes the marker visible and allows read_thread_terminal to return it. This confirms that rendering/read-back works when both clients genuinely share one session, but it is not an acceptable default workaround.

Expected
open_in_codex should preserve the exact supplied session ID across queuing and bind the visible terminal to that backend PTY, or return an explicit attachment failure instead of silently creating another shell.