Repository navigation
Background Terminal Sessions #3968
Description
What feature would you like to see?
Summary
Enable codex-cli to run terminal sessions in the background, similar to how Claude Code supports background terminals. This would allow long-running processes to continue without needing to keep the CLI window open, with the option to reattach later.
Problem
- Developers often run commands that take hours (servers, builds, migrations, log tails).
- Currently, they must keep codex-cli in the foreground or rely on external tools like
tmux,screen, ornohup. - This is inconvenient, error-prone, and inconsistent across platforms.
Goals
- Start commands as background sessions that survive terminal closure.
- Detach and reattach to a session with full TTY support.
- Provide log streaming and export without requiring reattachment.
- Ensure sessions are listed, inspectable, and manageable directly from codex-cli.
- Cross-platform support (macOS, Linux, WSL).
Non-Goals
- Full tmux replacement.
- Orchestrating sessions across multiple hosts.
Proposed UX
Examples
- Start a background process:
codex run --bg --name api-dev "pnpm dev"
diff
Copy code
- List sessions:
codex sessions list
diff
Copy code
- Tail logs without attaching:
codex sessions logs api-dev --follow
arduino
Copy code
- Attach/detach:
codex sessions attach api-dev
bash
Copy code
- Stop/clean up:
codex sessions stop api-dev
codex sessions rm api-dev
markdown
Copy code
Config Options
- Storage directory for session metadata and logs
- Maximum session count
- Log rotation and retention settings
- Idle timeout or TTL for auto-expiration
Benefits
- Improves developer productivity by reducing reliance on external tools.
- Provides a unified workflow for running and managing long-running processes.
- Makes codex-cli more competitive with similar tools that already provide background terminal support.
Alternatives Considered
- Continue relying on tmux/screen. Works but adds complexity and reduces portability.
- Use
nohupor&in shell. Limited functionality, no reattachment or lifecycle management.
Acceptance Criteria
- Background sessions survive CLI and terminal restarts.
- Users can list, inspect, attach, detach, and stop sessions.
- Logs are captured and exportable.
- Works across macOS, Linux, and WSL with minimal setup.
Are you interested in implementing this feature?
Yes
Additional information
No response
Activity
bearyung commentedon Sep 23, 2025
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.
roshanasingh4 commentedon Sep 25, 2025
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.
tekn0x commentedon Oct 4, 2025
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."
eladcandroid commentedon Oct 5, 2025
Helpful issue
That's the current state:
Wating too long time..
[-]Feature Request: Background Terminal Sessions[/-][+]Background Terminal Sessions[/+]myudak commentedon Nov 28, 2025
yeah pls, i hate this limitation, the gpts are so lazy in the codex
zssz commentedon Mar 16, 2026
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/listMotivation:
thread/backgroundTerminals/clean, so clients had to fall back to heuristics based on historical turn items or live outputWhat the branch adds:
thread/backgroundTerminals/listcallId,processId,command,cwd,tty,startedAtstartedAtReady branch:
0787de962Verification run:
cargo run -p codex-app-server-protocol --bin write_schema_fixturescargo test -p codex-app-server-protocolcargo test -p codex-app-server --test all thread_background_terminalsI can’t open the upstream PR directly because
openai/codexcurrently restricts PR creation to collaborators. If this looks like a useful direction, would a maintainer be willing to either:If you’d prefer this discussed in a separate issue instead of this umbrella one, I can do that too.
Fix Codex-driven invocation: timeout, state lock, softer session_id, …
xbyang42 commentedon Jun 15, 2026
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.
weathon commentedon Jul 22, 2026
Yes, I am running deep learning research and codex keep polling on it, burning tokens fast
etraut-openai commentedon Aug 5, 2026
/psand app-server APIs implement background-terminal management.PierreMesure commentedon Aug 16, 2026
On my setup, Codex regularly tries to use
nohupand fails before actually using a background terminal command compatible with/ps. To the point that I had to add that the AGENTS.md:## Don't use nohup Your sandbox doesn't let you.