Codex Session Viewer

Read-only terminal viewer for Codex session history stored under .codex.

The npm entry package is @afffun/codexsess. Public release packaging is being structured as:

• Root meta package: @afffun/codexsess
• Linux x64 binary package: @afffun/codexsess-linux-x64
• macOS Intel binary package: @afffun/codexsess-darwin-x64
• macOS Apple Silicon binary package: @afffun/codexsess-darwin-arm64
• Windows x64 binary package: @afffun/codexsess-win32-x64

For Linux x64, the release target should be a musl-linked binary so installs remain compatible with older glibc baselines such as Debian 12.

Repository Model

Recommended distribution model for this project:

• Keep the source repository private.
• Use GitHub Actions in that private repository to build release binaries.
• Publish the npm packages publicly.
• If desired, maintain a separate public showcase or marketing repository that does not contain the private source tree.

This means @afffun/codexsess can stay publicly installable without making the Rust source repository public.

What It Does

• Reads session index data from state_5.sqlite when available.
• Falls back to scanning sessions/**/*.jsonl directly.
• Shows a three-pane terminal UI with session list, normalized event timeline, and detail view.
• Automatically switches to a compact single-pane tabbed layout on narrow screens such as iPhone terminal sessions.
• Supports keyboard navigation, mouse wheel scrolling, search, filtering, copying, follow mode, and session export.
• Defaults the Timeline to newest-first ordering, supports t to toggle ordering, and supports p to jump directly to a timeline page in large sessions.
• Defers loading very large sessions until you explicitly request them, so the UI can still open instantly on constrained terminals.
• Shows the running app version on the splash, footer, and in-app help overlay.
• Checks npm for a newer @afffun/codexsess release on startup and can prompt you to update immediately, then relaunch into the new build, or skip.
• Keeps the implementation in Rust while exposing a CLI entrypoint through npm.

Run Locally

cargo run --

To skip sqlite and only scan JSONL files:

cargo run -- --no-sqlite

To export a specific session instead of launching the TUI:

cargo run -- export --session <session-id> --format markdown --output session.md

npm Wrapper

The npm package is a distribution layer for the Rust binary.

• bin/codex-session-viewer.js launches the platform binary.
• lib/resolve-binary.mjs resolves the binary from:
  • CODEX_SESSION_VIEWER_BINARY
  • dist/codex-session-viewer
  • an installed optional platform package such as @afffun/codexsess-linux-x64
  • vendor/<platform>-<arch>/codex-session-viewer
  • target/release/codex-session-viewer
  • target/debug/codex-session-viewer

Typical local workflow:

npm run build:bin
node ./bin/codex-session-viewer.js

Planned public package name:

npm install -g @afffun/codexsess
codexsess

Release Packaging

The repository now includes platform package manifests under npm/ and a release workflow under .github/workflows/release.yml.

This workflow is intended to run from the private source repository. The source can remain closed while the published npm packages stay public.

For the GitHub Actions publish path, add an NPM_TOKEN repository secret in the private source repository. The workflow uses that secret to publish the platform packages and the root meta package to the public npm registry.

Expected release order:

1. Build and publish each platform package first.
2. Publish the root @afffun/codexsess meta package after the platform packages are available.

Current platform matrix in the workflow:

• Linux x64 via x86_64-unknown-linux-musl
• macOS x64 via x86_64-apple-darwin
• macOS arm64 via aarch64-apple-darwin
• Windows x64 via x86_64-pc-windows-msvc

The helper script below stages a compiled binary into a platform package directory before packing or publishing:

node ./scripts/stage-platform-binary.mjs npm/linux-x64 target/x86_64-unknown-linux-musl/release/codex-session-viewer

Controls

• Tab / Shift-Tab: cycle focus
• Ctrl-H / Ctrl-L: previous / next pane
• Up / Down / j / k: move selection
• Ctrl-P / Ctrl-N: move selection up / down
• PageUp / PageDown: page through the active pane
• s: session search
• Ctrl-S: session search
• /: timeline search
• Ctrl-F: timeline search
• p: jump to a timeline page when Timeline is focused
• t: toggle timeline order between newest-first and oldest-first
• Enter: load a deferred large session, or in compact mode drill from sessions to timeline to detail
• l: load the selected deferred large session
• Paste while searching: inserts pasted text into the active search box
• 1-7: toggle timeline filters
• 0: restore default filters
• a: enable all filters
• r: toggle normalized/raw detail
• f: toggle follow mode
• R: reload sessions
• y: copy current item
• o: copy current raw JSON
• Y: copy current session export
• x: export current session to Markdown
• X: export current session to JSON
• ?: help
• u: install an available npm update when the update prompt is open
• q: quit

Data Caveats

• The viewer is strictly read-only against .codex.
• Codex storage formats are internal and may change between CLI versions.
• Hidden/internal reasoning items may exist only as encrypted payloads and cannot be reconstructed.
• Terminal clipboard behavior varies by local desktop, SSH session, and terminal emulator.
• On iPhone terminal apps such as iSH, compact layout and keyboard shortcuts are more reliable than mouse-like touch events. Tap and wheel behavior only work if the terminal app emits mouse events.
• Very large sessions are intentionally not auto-loaded on startup. Select them and press Enter or l when you actually want to parse them.