cx

README

cx

cx is a fast local Codex session picker for the terminal.

It reads Codex's local session state, shows all previous threads sorted by last updated, supports immediate search and preview/detail views, then delegates continuation back to Codex:

codex --yolo -C <session-cwd> resume <session-id>
codex --yolo -C <session-cwd> fork <session-id>

Install

go install github.com/ardasevinc/cx/cmd/cx@latest

Requirements:

• Codex CLI available as codex.
• Local Codex state under ~/.codex.

Privacy and compatibility

cx is local-only. It reads Codex session metadata/transcripts from your machine and launches the codex CLI; it does not upload session data or call a remote service.

Codex's local storage format is not a stable public API. cx follows the currently observed ~/.codex/state_5.sqlite, ~/.codex/session_index.jsonl, and rollout JSONL formats, so future Codex releases may require compatibility updates.

Use

cx
cx --list --limit 20
cx list --limit 20
cx new
cx new "debug oauth staging"
cx new --cwd ~/programming/open-source/cx
cx index status
cx index refresh
cx index rebuild
cx doctor
cx update --check
cx update
cx version
cx -V
cx --no-alt-screen

cx --help prints the full CLI, flag, key, and command reference.

cx index refresh incrementally builds the local transcript cache at ~/.cache/cx/index.sqlite. The cache is disposable; Codex's own ~/.codex/state_5.sqlite and rollout JSONL files remain authoritative. Transcript search and richer previews use the cache when available and degrade to metadata-only behavior when it is empty or unavailable.

cx index status --json and cx doctor --json expose cache health, FTS availability, missing/failed/truncated sessions, cache size, and storage-shape compatibility checks for automation.

cx new [name] creates a fresh local chat directory under ~/Documents/Codex/YYYY-MM-DD/ using the local date, then launches:

codex --yolo -C <created-dir>

If no name is provided, it creates the next chat-001, chat-002, ... directory. Named chats are slugged and collision-free, so an existing folder is never overwritten. cx new --cwd DIR starts a fresh Codex thread in an existing project directory with the same --yolo -C launch contract.

cx update --check compares the current binary to the latest GitHub tag. cx update installs the latest tagged release with:

go install github.com/ardasevinc/cx/cmd/cx@<latest-tag>

Keyboard:

• type to search
• arrows, ctrl+j/ctrl+k, mouse wheel, page keys, home/end to move
• left/right close/open the selected group in grouped views
• enter resumes a session, starts the selected new chat/project row, or toggles a group
• ctrl+n starts a fresh Codex thread in the selected session/project context
• ctrl+p opens the project launcher
• ctrl+g opens grouped projects
• ctrl+f to run codex fork <session-id>
• y copies the selected session id
• : opens command mode
• ? opens help
• tab toggles preview
• ctrl+e toggles detail view
• ctrl+v toggles compact/comfy rows
• esc/ctrl+c exits

Plain j and k enter the search query. The direct vim-ish movement keys are kept on ctrl+j and ctrl+k so search stays immediate.

Command mode:

:new [name]
:resume
:fork
:copy id|path|cwd|title|resume|fork
:view all|chats|projects|grouped|compact|comfy
:group projects|chats
:open | :close | :toggle | :open-all | :close-all
:preview
:detail
:clear
:quit

Development

just gate
just fmt
just test
just lint
just build

License

MIT