codex-session-mining

Search and audit Codex session rollout JSONL files to recover prior work and workflow friction.

Updated May 18, 2026
One-click install
npx skills add https://github.com/Joey-Tools/codex-private-workflows --skill codex-session-mining-joey-tools
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: codex-session-mining
Source: https://github.com/Joey-Tools/codex-private-workflows/tree/main/personal_codex/skills/codex-session-mining
Command: npx skills add https://github.com/Joey-Tools/codex-private-workflows --skill codex-session-mining-joey-tools

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Recovering prior work, commands, or decisions from a large local Codex history is difficult because session data is spread across session_index.jsonl, history.jsonl, and thousands of rollout JSONL files under active and archived roots. This Skill locates the smallest relevant transcript set and extracts only the decisive evidence without dumping entire files into context. ## Core Features & Use Cases - Session Recovery: Map a session ID, thread ID, date window, repo path, or user phrasing to exact rollout files across both active and archived session roots. - Bounded Scanning: Use scan_rollout.py for value-free structural orientation and field-aware literal search with strict byte, record, and output budgets. - Corpus Audits: Use build_session_corpus.py to build a deduplicated cross-root corpus for date-window audits, replay-prefix detection, and repeated workflow-friction analysis. - PR Attribution: Use pr_attribution.py to derive the exact OpenAI Codex PR attribution sentence from a task family's model and effort votes. - Use Case: When asked to "read your rollout" or audit skill trigger misses over the last week, inventory both transcript roots, select candidate rollouts, and scan each one with bounded field-aware search instead of raw grep. ## Quick Start Ask the assistant to use the codex-session-mining skill to find what was done in a recent Codex session by date or session ID.

Frequently Asked Questions about codex-session-mining

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I find a previous Codex session by ID or date?

Look up the session ID or thread name in session_index.jsonl and history.jsonl first, then select candidate rollout files under sessions/YYYY/MM/DD and archived_sessions. For date windows, inventory both roots and filter the union by record timestamps rather than file mtime.

How do I search Codex rollout JSONL files without flooding context?

Use scan_rollout.py shapes for value-free structural orientation and scan_rollout.py search for bounded field-aware literal search on one exact rollout. Avoid raw rg or jq whole-record scans, which can dump huge nested tool outputs into context.

Can this audit sessions across both active and archived roots?

Yes. build_session_corpus.py inventories both sessions/ and archived_sessions/, including flat and date-nested archive layouts, and writes a deduplicated corpus.jsonl. It collapses only byte-identical copies or replay prefixes while retaining distinct later follow-ups.

Why do old records appear with new timestamps in a rollout?

Resumed, forked, compacted, or restored rollouts can copy and restamp earlier history into the current file. The Skill detects replay signals such as dense bursts and repeated session_meta boundaries, then deduplicates only the replayed prefix against stable record fingerprints.

Does this Skill modify my ~/.codex directory?

No. The workflow is read-only unless the user explicitly asks to modify ~/.codex. Its scripts only inventory, hash, and scan rollout files, and interrupted corpus runs are classified as incomplete rather than silently cleaned up.