Codex Session Manager

Simple TUI to rename, tag, and archive Codex CLI sessions stored under ~/.codex.

What it does

• Browse sessions with a focused cursor and optional bulk selection
• Rename sessions and edit tags
• Archive or unarchive sessions
• Search by name or tag and filter by archive status
• Toggle a details pane with metadata and previews of the first and last messages
• Tag autocomplete in the tag editor
• Bulk toggle archive status for selected sessions

Requirements

• Node.js 18.18+ or 20.9+ (or newer)

Install

npm install

Build and run

npm run build
npm start

Quality checks

npm run typecheck
npm run lint
npm test

Dev run (tsx)

npm run dev

Controls

Navigation

• Up/Down (j/k): move focus
• p/n: page up/down
• g : jump to top
• G : jump to bottom

Filter and view

• / : search by name or tag
• f : show filter (active, archived, active+archived)
• s : toggle sort order (desc/asc)
• d : toggle details pane

Selection

• space : toggle selection for bulk actions
• A : select all visible
• I (capital i): invert selection
• C : clear selection

Actions

• r : rename session
• t : edit tags (comma separated)
• a : toggle archive focused
• B : toggle archive selected

Other

• h or ? : toggle help
• q : quit

Note: In-app help (h/?) includes alternate keys like Home/End and Tab.

Notes

• Session metadata is stored in the first JSON line (session_meta) inside each .jsonl file.
• This tool adds or updates title, name, and tags in that line.
• Archiving moves files into ~/.codex/archived_sessions and restoring moves them back into the date-based folder.
• Windows: Works in Windows Terminal or PowerShell 7+ (ANSI + raw mode). Session data still lives under %USERPROFILE%\.codex.

Example use cases

• Rename a session so it is easy to spot in --resume lists.
• Tag sessions with project names for quick filtering.
• Archive old sessions to keep the active list clean.