codex-logs

A CLI tool to browse and view OpenAI Codex CLI session logs interactively.

Why I Built This

Codex CLI stores conversation logs as JSONL files in ~/.codex/sessions/, organized by date. Browsing through these nested directories manually is cumbersome. I wanted a quick way to:

• Find past sessions by month and date
• See project and branch info at a glance
• Preview conversations before opening
• Watch active sessions in real-time

Features

• Interactive Selection: Use fuzzy finder (fzf) to browse months and sessions
• Session Preview: See conversation snippets and project info before opening
• Real-time Monitoring: Watch active sessions with tail command
• Git Context: Display project directory and branch for each session
• Formatted Output: Color-coded display of user/assistant messages
• Status Check: See if Codex CLI is running and view recent sessions

Demo

demo.mp4

Requirements

• macOS (uses stat -f for file timestamps)
• fzf - Fuzzy finder
• jq - JSON processor
• Codex CLI installed

Installation

Using Homebrew (for dependencies)

brew install fzf jq

Install the script

# Clone the repository
git clone https://github.com/wondercoms/codex-logs.git

# Make it executable
chmod +x codex-logs/codex-logs

# Add to your PATH (choose one)
# Option 1: Copy to local bin
cp codex-logs/codex-logs ~/.local/bin/

# Option 2: Add to PATH in your shell config
echo 'export PATH="$PATH:/path/to/codex-logs"' >> ~/.zshrc

Usage

# Interactive mode - browse months and sessions with fzf
codex-logs

# List all months with session counts
codex-logs list

# View the latest session across all months
codex-logs latest

# Watch the latest session in real-time
codex-logs tail

# Check Codex CLI status and recent sessions
codex-logs status

# Show help
codex-logs help

Commands

Command	Description
(none)	Interactive mode - select month → session with fzf
list	Show all months (YYYY/MM) with session counts
latest	View the most recent session across all months
tail	Watch the latest session in real-time
status	Check if Codex CLI is running + show 3 most recent sessions
help	Show help message

Output Format

The tool formats JSONL logs into readable conversations:

━━━━━━━━━━ USER ━━━━━━━━━━
Your message here...

━━━━━━━━━━ CODEX ━━━━━━━━━━
Codex's response here...

Session info includes project directory and git branch:

=== rollout-xxx.jsonl ===
Project: /path/to/project | Branch: main

How It Works

Codex CLI stores sessions in ~/.codex/sessions/YYYY/MM/DD/ as JSONL files. This tool:

1. Scans the nested date-based directory structure
2. Groups sessions by month for easier navigation
3. Parses JSONL to extract messages and session metadata
4. Uses fzf for interactive selection with previews
5. Formats output with ANSI colors for readability

License

MIT

Contributing

Issues and PRs welcome!