Codex Session Daemon

Upgrade-resilient session management for OpenAI Codex CLI that automatically saves and restores conversation sessions organized by project.

🎯 Features

• Automatic Session Saving: Captures all Codex conversations automatically
• Project Organization: Sessions organized by Git repos, Node/Rust/Python projects
• Upgrade Resilient: Uses only Codex's stable APIs (MCP + notifications)
• Auto-Resume: Automatically resume recent sessions in the same project
• Zero Code Changes: No modifications to Codex core - pure extension

🚀 Quick Start

# Install and configure
cd codex-session-daemon
./install.sh

# Start using Codex normally - sessions save automatically!
cd ~/my-project
codex "help me implement user authentication"

# List saved sessions
codex-session-daemon list

# View session details  
codex-session-daemon show <session-id>

🏗️ How It Works

The daemon integrates with Codex using two extension points:

1. MCP Server: Provides tools like list_sessions, load_recent_session
2. Notification Hooks: Captures events when Codex completes turns

Codex CLI ──┬── MCP Tools ──→ Session Daemon
            └── Notifications ──→ Session Daemon
                                      │
                                      ▼
                               ~/.codex/projects/
                               ├── my-project/
                               │   ├── sessions/
                               │   │   ├── abc-123.jsonl
                               │   │   └── def-456.jsonl  
                               │   └── metadata/
                               └── other-project/

📁 Session Storage

Sessions are stored in ~/.codex/projects/[project-name]/:

• sessions/: Individual session files in JSONL format
• metadata/: Session indexes and search data

Each session includes:

• Full conversation history
• Project context (Git branch, files)
• Timestamps and metadata
• Tool calls and command outputs

🔧 Configuration

The installer automatically adds this to ~/.codex/config.toml:

# Session management integration
notify = ["codex-session-daemon", "event"]

[mcp_servers.session_manager]
command = "codex-session-daemon"
args = ["mcp"]
env = {}

🎛️ Commands

# List sessions for current project
codex-session-daemon list

# Show detailed session conversation
codex-session-daemon show <session-uuid>

# Start MCP server (used by Codex)
codex-session-daemon mcp

# Process notification event (used by Codex)
codex-session-daemon event '{"type":"agent-turn-complete",...}'

🔍 Project Detection

Automatically detects project types by scanning for:

• Git repos: .git/ directory
• Rust: Cargo.toml
• Node.js: package.json
• Python: pyproject.toml, setup.py
• Go: go.mod

Sessions are organized by the detected project root directory name.

🔄 Auto-Resume (Future)

The daemon can automatically suggest resuming recent sessions:

• Detects when you return to a project
• Matches Git branch and working directory
• Offers to restore conversation context
• Seamless continuation of previous work

🛡️ Upgrade Safety

This daemon is completely upgrade-resilient because it:

• ✅ Uses only stable Codex APIs (MCP protocol + notifications)
• ✅ No modifications to Codex source code
• ✅ Configuration-only integration
• ✅ Runs as separate process
• ✅ Works across all Codex version upgrades

🚧 Development Status

• ✅ Core session capture and storage
• ✅ Project detection and organization
• ✅ MCP server interface
• ✅ Command-line session management
• 🔄 Auto-resume integration (in progress)
• 🔄 Session search and filtering
• 🔄 Conversation export formats

🔨 Building

# Build release binary
cargo build --release

# Run tests
cargo test

# Development mode
cargo run -- --help

📋 Requirements

• Rust 1.70+
• OpenAI Codex CLI installed
• Git (for project detection)

🤝 Contributing

This is a minimal viable prototype. Contributions welcome for:

• Enhanced session search
• Multiple export formats
• Session compression/archiving
• Web UI for session browsing
• Integration with other AI CLIs

📄 License

MIT License - see LICENSE file for details.