Background Terminal Sessions

this will be extremely useful. when using Claude Code CLI, Claude can automatically run several server (dotnet run dev, npm run dev) in background, and check the server side error during the frontend test using playwright mcp, observe the errors thrown in different servers (maybe one for auth, one for transaction and one for user preference), and fix the bug automatically, build and kill those servers and run that again to verify the fix.

Also I used to ask Claude Code to add different diagnoses logs on server side when testing the APIs.

Thanks @bearyung - your example really highlights the value here.

Even a minimal version with run --bg, sessions list, attach/detach, and basic log capture would cover most needs. Lifecycle management (TTL, cleanup, export) could be added incrementally once the core flow is solid.

Would be great to hear if maintainers see this phased approach as feasible.

Yes please. I currently add this to my prompts as a work around: "You also need to run all servers as background processes or else you will get stuck forever. Tail any logs you need to see."

Helpful issue
That's the current state:

<img width="1053" height="206" alt="Image" src="https://github.com/user-attachments/assets/57b89b44-ecb0-4e74-a99b-0faae24bcaa0" />

Wating too long time..

yeah pls, i hate this limitation, the gpts are so lazy in the codex

I have a working implementation for one piece of this in my fork and wanted to ask whether maintainers would be open to taking it.

This change adds an experimental app-server API:

• thread/backgroundTerminals/list

Motivation:

• a client can keep long-lived background terminals running on the server
• after reconnect or client restart, it had no authoritative way to rediscover those sessions
• the only server API in this area was thread/backgroundTerminals/clean, so clients had to fall back to heuristics based on historical turn items or live output
• this listing API gives reconnect flows a stable source of truth and reduces client-side guesswork

What the branch adds:

• protocol + app-server wiring for thread/backgroundTerminals/list
• live unified-exec metadata: callId, processId, command, cwd, tty, startedAt
• thread/core support to enumerate active background terminals
• deterministic ordering by startedAt
• protocol tests, app-server tests, schema updates, and README docs

Ready branch:

• fork branch: https://github.com/zssz/codex/tree/zssz/background-terminal-list-api
• compare: https://github.com/openai/codex/compare/main...zssz:zssz%2Fbackground-terminal-list-api?expand=1
• commit: 0787de962

Verification run:

• cargo run -p codex-app-server-protocol --bin write_schema_fixtures
• cargo test -p codex-app-server-protocol
• cargo test -p codex-app-server --test all thread_background_terminals

I can’t open the upstream PR directly because openai/codex currently restricts PR creation to collaborators. If this looks like a useful direction, would a maintainer be willing to either:

• open the PR from my fork branch, or
• grant temporary collaborator access so I can open the draft PR myself?

If you’d prefer this discussed in a separate issue instead of this umbrella one, I can do that too.

I hope the official team can implement this feature, similar to Claude Code's run_in_background.
A typical use case is having Codex perform deep learning auto research. Claude Code can submit a training task and then suspend the command to the background. Once training is complete, it can be reactivated for the next steps of testing and result analysis. In contrast, Codex, on the other hand, constantly polls to check if training is finished—even though the training task might last for several days.