Codex Session Viewer

codex-session-viewer is a small CLI for reading local Codex session .jsonl files when you want to browse, search, or export chats outside the default UI.

Features

• List local Codex sessions with index numbers
• Open a session and print messages in a readable terminal format
• Export a session to Markdown, text, or JSON
• Search all sessions for a keyword
• Override the default sessions folder with --path

Requirements

• Node.js 14 or newer
• npm 6 or newer
• Codex installed with at least one recorded session

Install

npm install

For local CLI testing:

npm link

Install From npm

Once this package is published to npm, people will be able to install it in either of these ways.

Global install:

npm install -g codex-session-viewer
codex-view list

Project-local install:

npm install codex-session-viewer
npx codex-view list

If the package name codex-session-viewer is already taken on npm, update the name field in package.json before publishing.

Quick Start

Windows (PowerShell or Command Prompt)

1. Open a terminal in this project folder.
2. Install dependencies:

npm install

3. Link the CLI on your machine:

npm link

4. Try the first commands:

codex-view list
codex-view open 0 --chat-only --compact
codex-view export 0 --format txt

5. If your sessions are not found automatically, pass the Codex sessions path explicitly:

codex-view --path "$HOME\.codex\sessions" list

macOS/Linux

1. Open a terminal in this project folder.
2. Install dependencies:

npm install

3. Link the CLI on your machine:

npm link

4. Try the first commands:

codex-view list
codex-view open 0 --chat-only --compact
codex-view export 0 --format txt

5. If your sessions are not found automatically, pass the Codex sessions path explicitly:

codex-view --path "$HOME/.codex/sessions" list

Without npm link

If you do not want to link the command globally, you can run it directly from this repository:

npm start -- list

Windows example:

node .\bin\index.js list

macOS/Linux example:

node ./bin/index.js list

Usage

By default the CLI reads from ~/.codex/sessions.

codex-view list
codex-view --plain list
codex-view list --recent 10
codex-view list --json
codex-view open 0
codex-view open 0 --compact
codex-view open 0 --chat-only
codex-view open 0 --chat-only --compact
codex-view open 0 --json
codex-view export 0
codex-view export 0 --chat-only
codex-view export 0 --format txt
codex-view export 0 --format json
codex-view export 0 --output exports/session-0.md
codex-view export 0 --output exports/session-0.md --force
codex-view search "keyword"
codex-view search "keyword" --recent 20
codex-view search "keyword" --chat-only
codex-view search "keyword" --json
codex-view search "keyword" --exact
codex-view search "Keyword" --case-sensitive

Use a custom sessions path:

codex-view --path /custom/path/to/sessions list

You can also run the CLI without linking:

npm start -- list

Project Structure

bin/index.js
src/commands/list.js
src/commands/open.js
src/commands/export.js
src/commands/search.js
src/utils/fileReader.js
src/utils/parser.js
src/utils/formatter.js
src/constants/paths.js

Notes

• Invalid JSON lines are skipped with a warning
• Empty or missing session folders produce friendly errors
• Exported files are written to the current working directory by default
• Use codex-view open <index> --compact for a fast scan view
• Use codex-view open <index> --chat-only to keep just the main user prompts and final assistant replies
• Use codex-view open <index> --json for full session extraction in scripts
• Use codex-view --plain ... or NO_COLOR=1 for logs, CI, or simple terminals
• Use codex-view list --recent <n> to focus on the newest sessions first
• Use codex-view list --json for automation and scripting
• Use codex-view search "keyword" --recent <n> to narrow search to recent sessions
• Use codex-view search "keyword" --chat-only to ignore commentary noise
• Use codex-view search "keyword" --json for machine-readable search results
• Use codex-view search "keyword" --exact to require an exact full-message match
• Use codex-view search "Keyword" --case-sensitive to preserve case in matching
• Use codex-view export <index> --chat-only for a cleaner transcript
• Use codex-view export <index> --format txt for a plain text transcript
• Use codex-view export <index> --format json for machine-readable export data
• Use codex-view export <index> --output <file> to control where the export file goes
• Use --force with export only when you want to overwrite an existing file

Development

Run the local test suite:

npm test

This repository also includes a GitHub Actions workflow at .github/workflows/ci.yml that runs the tests on pushes and pull requests.

Publish To npm

1. Make sure you are logged in to npm:

npm login

2. Verify exactly what will be published:

npm pack --dry-run

3. Publish the package publicly:

npm publish

After publishing, anyone should be able to install it with:

npm install -g codex-session-viewer