[codex-rs][experiment] New session crate to manage backgrounded codex execution

[oai-ragona]

What/Why

I often find myself wanting to drop in and out of a codex session, or just fire off a read-only background task like, "analyze this folder, and look for bugs." I don't want to have to watch the thing closely, I just want it to go work.

Implementation

This PR is largely codex-rs generated, and I still need to review it myself. At a high level, it adds a new codex-session bin target. It's a CLI closer to something like docker or kubectl, where it's effectively a CRUD interface that just wraps the other bins.

➜  codex-session
Manage background Codex agent sessions

Usage: codex-session <COMMAND>

Commands:
  create  Spawn a new background session
  attach  Attach the current terminal to a running interactive session
  delete  Terminate a session and remove its on-disk state
  logs    Show (and optionally follow) the stdout / stderr logs of a session
  list    List all known sessions
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

The high level flow works by tracking session folders with stdin/out/metadata in ~/.codex/sessions.
We can list previous sessions we've done:

➜  ~ codex-session list
#   ID                 PID    TYPE  STATUS  OUT   ERR  CREATED                           PROMPT
0   dirty-detail-8837  84414  repl  exited  666B  0B   2025-04-26T15:24:00.110923+00:00  hey
1   spicy-level-7178   84217  exec  exited  383B  0B   2025-04-26T15:23:29.305278+00:00  list files

See how they went:

➜  ~ codex-session logs spicy-level-7178 | tail -5
rustfmt.toml
session
target
tui
Task complete: 1

We can drop in and out of running interactive repl sessions with attach:

➜  ~ codex-session create repl "oh hello there" --allow-no-git-exec
victorious-bells-7987
➜  ~ codex-session attach victorious-bells-7987
user> initializing session
user> waiting for session initialization
user> session initialized
user> sending request to model
codex> event: TaskStarted
codex> Hello! How can I help you today?
user>
just saying hi
user> sending request to model
codex> event: TaskStarted
^C
➜  ~
➜  ~ codex-session logs 0 | tail -3
codex> event: TaskStarted
codex> Hi back at you! 👋
Hope you’re having a good day. If there’s anything you’d like to chat about or any question I can help with, just let me know!
user> %

I think a little wrapper like this would quickly become my preferred interface to launch codex tasks, and I think we can actually get it working just fine with any type of TUI, so in theory this should be able to wrap any of them. Still in draft mode trying this stuff out and reviewing the model-generated xode.

[kshitizz36]

Hi @oai-ragona,

Thanks for contributing this! I noticed your PR #684 ([codex-rs][experiment] New session crate to manage backgrounded codex execution). It looks like it aims to solve a similar problem to the one I'm addressing in my own PR, #522 (feat(cli): add multi-session management subcommands for Codex CLI).

My approach in #522 focuses on adding manual session save, load, list, and delete subcommands directly to the existing Node.js CLI. The goal is to allow users to explicitly save the state (like model, instructions, context) of an interactive session and restore it later, mainly for context switching or preserving complex interactive states after they've been established.

From your description, it seems your implementation (codex-session bin, background tasks, attach) might be targeting a slightly different or perhaps broader scope, possibly involving background execution and a more Docker/kubectl-like interface for managing potentially running or backgrounded sessions.

[oai-ragona]

Hi @oai-ragona,

Thanks for contributing this! I noticed your PR #684 ([codex-rs][experiment] New session crate to manage backgrounded codex execution). It looks like it aims to solve a similar problem to the one I'm addressing in my own PR, #522 (feat(cli): add multi-session management subcommands for Codex CLI).

My approach in #522 focuses on adding manual session save, load, list, and delete subcommands directly to the existing Node.js CLI. The goal is to allow users to explicitly save the state (like model, instructions, context) of an interactive session and restore it later, mainly for context switching or preserving complex interactive states after they've been established.

From your description, it seems your implementation (codex-session bin, background tasks, attach) might be targeting a slightly different or perhaps broader scope, possibly involving background execution and a more Docker/kubectl-like interface for managing potentially running or backgrounded sessions.

Hey @kshitizz36!

Explicitly saving and restoring the state of an interactive session would be great. I haven't taken a close look at your PR yet, but the idea is something I've wanted as well, and is non-overlapping with what I'm up to here.

This PR is about spinning off lots of little mostly non-interactive agents. It's currently just for the extra-experimental codex-rs Rust fork, where we're experimenting with a design meant to compliment rather than replace the main TypeScript version. The idea is that the core can be separated out into a simple async interface, and then we can try different types of CLI and TUI experience. (One note is that currently codex-session only manages non-interactive or simple stdin/out processes.)

What I'm working on is, as you note, much more similar to docker or kubectl. Here is an example from me trying out this branch today. I've been using the fully non-interactive exec bin in codex/codex-rs/exec, which is configured to always be fully sandboxed, and to never escalate to the user for interaction, so it works for one-shot tasks that don't need steering.

➜  codex-rs codex-session list
#   ID                PID    TYPE  STATUS  OUT        ERR   CREATED               PROMPT
0   crisp-owlet       34756  repl  exited  1.19 MB    0 B   2025-04-27T19:08:47Z  Your goal is to complete the below task ...
3   large-takin       28284  exec  exited  12.89 kB   0 B   2025-04-27T16:56:14Z  I'd like you to take a look at session/s...
4   meek-hare         20356  exec  exited  14.07 kB   0 B   2025-04-27T16:01:25Z  review the codebase, read PLAN.md, and f...
5   super-swift       19783  exec  exited  3.91 kB    0 B   2025-04-27T15:58:15Z  in codex-rs/session let's make it so the...
6   sunny-cony        15373  exec  exited  7.13 kB    0 B   2025-04-27T15:51:24Z  I'd like you to fully execute a PR to ad...

I'm planning to get this cleaned up and record a little demo video tomorrow, but in the mean time I'm happy to confirm this is totally separate from the mainline TypeScript codex, so I don't expect any merge conflicts or anything with your PR.

Best,
Ryan