Codex Session Manager

csm is a fast, folder-first terminal browser for local OpenAI Codex CLI sessions. Its interface follows the Miller-column navigation model used by lf: directories and sessions appear together, and the rightmost column previews whatever is highlighted.

parent entries     current directory                 hover preview

~/                 Documents/                        compiler/
                   Research/                         literature/
                   project-a/                        session-name  09-14 12:30
                   fix-cache-race  09-14 11:08
                   01a09fb9-...    09-13 19:42

Directories are blue. Sessions are magenta. Hovering a directory previews its children and sessions; hovering a session shows its name or ID, first prompt, timestamps, model, token count, Git metadata, and other details.

Note

This is an unofficial community tool. It is not affiliated with or maintained by OpenAI.

Features

• Miller-column navigation with at most three seamless panes
• Directories and sessions mixed at the level where they belong
• Session names with UUID fallback—never a generated first-message title
• Read-only access to the local Codex session index
• Resume a selected session with codex resume
• Browse archived sessions and restrict browsing to a directory subtree
• Optional csmcd zsh wrapper that changes the parent shell's directory
• No third-party Python runtime dependencies

Platform support

Platform	Status
Linux	Tested and supported
macOS	Experimental; expected to work, but not yet tested by the maintainer
Windows	Not supported; WSL may work but is untested

Codex CLI itself supports macOS and Linux. csm uses portable Python standard library modules (curses, sqlite3, and pathlib) and POSIX paths, so there is no known code-level blocker on macOS. However, csm reads Codex's local session database, which is an internal storage format rather than a stable public API. Please open an issue if a Codex update or macOS installation uses a different layout.

Requirements

• Linux, or macOS for experimental use
• Python 3.10+
• OpenAI Codex CLI, available as the codex command
• A terminal with color and Unicode support
• zsh only if you want the csmcd shell wrapper

Installation

Clone the repository and install it:

git clone https://github.com/flora6907/codex-session-manager.git
cd codex-session-manager
python3 -m pip install --user .

Ensure your user binary directory is in PATH. It is commonly ~/.local/bin on Linux. Then launch the browser:

csm

For development, use an editable install:

python3 -m pip install --user -e .

zsh integration

A subprocess cannot change the directory of its parent shell. Source the included wrapper if you want c to leave your shell in the selected directory and session resume to begin there:

zshrc="${ZDOTDIR:-$HOME}/.zshrc"
printf '\nsource "%s/shell/csm.zsh"\n' "$PWD" >> "$zshrc"
source "$zshrc"

Use csmcd instead of csm after enabling the wrapper.

Navigation

Key	Action
j / k, up/down	Move the highlight
h, left	Go to the parent directory
l, right, Enter	Enter the highlighted directory
r	Resume the highlighted session
c	Select the current directory and quit; requires csmcd to change the shell
.	Toggle hidden directories
g / G	Jump to the first / last entry
Page Up / Page Down	Move ten entries
q, Esc	Quit

Hovering is enough to preview. A directory shows its next Miller column, while a session shows its detailed metadata. Resuming is deliberately assigned to r so inspecting a session is non-destructive.

Command-line options

csm --help
csm --root ~/Research       # only sessions under this subtree
csm --include-archived      # include archived sessions
csm --list                  # emit active sessions as JSON Lines
csm --codex-home PATH       # use a different Codex data directory

The same options can be passed to csmcd.

How it works

csm looks in $CODEX_HOME, defaulting to ~/.codex. It opens the newest state_*.sqlite database in SQLite read-only mode and queries the threads index. If that index is unavailable, it falls back to reading metadata from sessions/**/*.jsonl and, when requested, archived_sessions/**/*.jsonl.

The tool does not edit, archive, delete, or rewrite Codex session data. The only external action it performs is codex resume SESSION_ID when you press r.

Development

The test suite uses only the Python standard library:

PYTHONPATH=src python3 -m unittest discover -s tests -v

License

MIT