feat(codex): Add session management with intelligent routing v2.2.0

[Jiusi-pys]

Summary

This PR adds comprehensive session management to the Codex plugin, enabling intelligent routing, cross-conversation persistence, and seamless multi-turn task continuity.

What's New in v2.2.0

Session Management

• Intelligent routing - Automatically routes queries to existing sessions based on keyword matching (>50% = resume, <50% = new session)
• Persistent registry - Session metadata stored at ~/.codex/claude-sessions.json, survives Claude Code restarts
• Cross-conversation continuity - Resume tasks started in previous conversations
• Implicit continuation - Detects "also", "continue" and auto-resumes last session

New Commands

• /codex:login - Authenticate via ChatGPT OAuth, device code, or API key
• /codex:logout - Remove stored credentials
• /codex:sessions [list|show <id>|cleanup] - Manage active sessions

Enhanced Agent

• codex-manager - Full session router with:
  • Keyword extraction and similarity matching
  • JSON output parsing (file changes, commands, approvals, summaries)
  • Approval handling via AskUserQuestion for file edits
  • Registry CRUD operations (create, read, update, archive)
  • Structured response summaries

Technical Improvements

• ✅ Fixed jq syntax for session cleanup (was completely broken)
• ✅ Added portable date calculation (supports macOS/BSD and Linux/GNU)
• ✅ Fixed session ID extraction for both new and resumed sessions
• ✅ Removed hardcoded CLI paths - uses global codex command
• ✅ Added temp file cleanup to prevent race conditions
• ✅ Updated all documentation to reflect global installation

Architecture

User Query → /codex command
    ↓
codex-manager Agent
    ↓
1. Extract keywords from query
2. Load ~/.codex/claude-sessions.json
3. Match existing session OR create new
4. Execute: codex resume <ID> OR codex exec --json
5. Parse JSON events (file changes, approvals, summaries)
6. Handle approval_request → AskUserQuestion
7. Update registry with results
8. Return structured summary

Session Registry Schema

{
  "version": "1.0.0",
  "sessions": [
    {
      "id": "uuid-from-codex",
      "task_summary": "Implement user authentication",
      "keywords": ["auth", "login", "jwt", "user"],
      "last_used": "2026-01-12T10:30:00Z",
      "status": "active"
    }
  ]
}

Usage Examples

First time - Login:

/codex:login
# Opens browser for ChatGPT OAuth
# Credentials saved to ~/.codex/auth.json

New task:

/codex "Implement user authentication with JWT"
# No matching session → creates new session abc-123
# Tracks keywords: ["authentication", "jwt", "user"]

Continue task:

/codex "Add refresh token to the authentication"
# Finds session abc-123 (100% keyword match)
# Resumes that session

Manage sessions:

/codex:sessions list       # Show all active sessions
/codex:sessions cleanup    # Archive old sessions

Files Changed

New Files (3):

• plugins/codex/commands/login.md - OAuth authentication
• plugins/codex/commands/logout.md - Credential removal
• plugins/codex/commands/sessions.md - Session management

Modified Files (4):

• plugins/codex/agents/codex-manager.md - Enhanced to full session router
• plugins/codex/skills/codex-integration/SKILL.md - Updated with session management docs
• plugins/codex/.claude-plugin/plugin.json - Version 2.2.0
• .claude-plugin/marketplace.json - Version 2.2.0

Breaking Changes

None - fully backward compatible. Existing workflows continue to work.

Testing

Tested on:

• macOS (BSD date)
• Session creation and resumption
• Keyword matching algorithm
• JSON parsing
• Registry persistence across restarts

Related Issues

Closes #[issue-number] (if applicable)

🤖 Generated with Claude Code