Feature Request: Background Terminal Sessions

[roshanasingh4]

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, or nohup.
• 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 nohup or & 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

[bearyung]

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]

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]

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]

Helpful issue
That's the current state:

Wating too long time..