Codexsess

Codexsess is a read-only terminal viewer for Codex session history stored under .codex.

It is built for large real-world sessions: you get a session list, normalized timeline, detail view, search, filtering, Markdown export, copy helpers, and npm-based self-update checks in one TUI.

Install

Global install:

npm install -g @afffun/codexsess
codexsess

One-off run:

npx @afffun/codexsess

What It Does

• Reads session index data from state_5.sqlite when available.
• Falls back to scanning sessions/**/*.jsonl directly.
• Shows a three-pane TUI for sessions, timeline, and detail.
• Switches to a compact layout on narrow terminals such as iPhone terminal apps.
• Supports search, paging, newest-first timeline browsing, follow mode, copy helpers, and Markdown export.
• Checks npm for a newer @afffun/codexsess release on startup.

Basic Usage

Open the default Codex home:

codexsess

If the machine exposes multiple .codex homes, Codexsess opens a source picker at startup so you can choose which one to browse. Codexsess remembers the last selected source and restores that source's browsing state independently.

Open a specific Codex home:

codexsess --codex-home /path/to/.codex

Open with raw detail enabled:

codexsess --raw

Skip sqlite and scan JSONL only:

codexsess --no-sqlite

Pre-filter sessions or timeline:

codexsess --session-query deploy --timeline-query error

Export one session without entering the TUI:

codexsess export --session <session-id> --format markdown --output session.md

Manage known Codex homes:

codexsess sources list
codexsess sources current
codexsess sources use /path/to/.codex
codexsess sources add /path/to/.codex
codexsess sources remove /path/to/.codex

Per-source state that is restored automatically includes:

• the last selected session
• session search text
• timeline search text
• timeline order
• timeline filters

Updating

Check for a newer version without installing:

codexsess update --check

Check npm and install the latest release if one exists:

codexsess update

When Codexsess starts, it also checks npm in the background. If a newer version exists, the startup prompt gives you three choices:

• u: install the update now
• s: skip only for the current run
• i: ignore that specific version until something newer is published

The persistent ignore state is stored locally under the Codexsess config directory.

In-App 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
• Home / End / g / G: jump to the start or end
• s or Ctrl-S: session search
• / or Ctrl-F: timeline search
• p: jump to a timeline page when Timeline is focused
• t: toggle timeline order between newest-first and oldest-first
• c: open the Codex home source picker
• 1-7: toggle timeline filters
• 0: restore default filters
• a: enable all filters
• Enter: load a deferred large session, or drill down in compact mode
• l: load the selected deferred large session
• r: toggle normalized/raw detail
• f: toggle follow mode
• R: reload sessions
• ?: open help
• q: quit

Copying And Export

• y: copy selected Detail text, or the current item body when nothing is selected
• o: copy the current raw JSON
• Y: copy the current session export as Markdown
• x: export the current session to Markdown after entering a directory
• X: export the current timeline item to Markdown after entering a directory

Desktop terminals often block native text selection while the TUI owns the alternate screen and mouse capture. On desktop, use in-app Detail selection instead:

1. Drag inside the Detail pane.
2. Press y.

Markdown exports include the session ID, rollout path, working directory, and Codex home. If the export directory prompt is left empty, Codexsess uses the current working directory.

Notes

• Codexsess is strictly read-only against .codex.
• When more than one Codex home is available, Codexsess treats each one as a separate source. It does not merge sessions across sources.
• 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.
• Very large sessions are intentionally not auto-loaded on startup. Select them and press Enter or l when you actually want to parse them.

Clipboard behavior depends on the local terminal environment:

• Wayland: ideally with wl-clipboard (wl-copy)
• X11: xclip or xsel
• tmux: set -g set-clipboard on
• Terminal protocol fallback: OSC52 support in the terminal emulator

In headless Linux shells without X11, Wayland, tmux clipboard integration, or OSC52 support, in-app selection can still work while desktop clipboard copy may not.

Local Development

Run the Rust binary directly:

cargo run --

Typical local npm wrapper workflow:

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

Package Layout

The npm entry package is @afffun/codexsess. Public release packaging is split into:

• 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

The npm wrapper 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

Release Packaging

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

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:

• 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