Codex Chat Search

Find past Codex conversations from the local history stored under ~/.codex.

This skill is intentionally offline-only. It reads local JSONL history files and does not send conversation contents to any service.

What it searches

• ~/.codex/session_index.jsonl for conversation ids, names, and update times.
• ~/.codex/sessions/**/*.jsonl for user-authored messages.
• ~/.codex/archived_sessions/**/*.jsonl as a fallback source.

The search prefers conversation titles and user messages over command output, diffs, logs, copied docs, and developer instructions.

Requirements

• Python 3.10 or newer.
• No third-party Python dependencies.

Usage

From this skill directory:

python scripts/find_codex_conversations.py --query "reescalar imagenes" --date 2026-04-21

Useful variations:

python scripts/find_codex_conversations.py --query "assembly" --max-results 5
python scripts/find_codex_conversations.py --date 2026-04-21 --query "raw" --query "imagen"
python scripts/find_codex_conversations.py --date-from 2026-04-20 --date-to 2026-04-21 --query "resume"
python scripts/find_codex_conversations.py --query "imagenes" --json
python scripts/find_codex_conversations.py --query "imagenes" --verbose

By default, text output includes only:

• Nombre
• Fecha
• Ultimo mensaje usuario
• Descripcion

Use --verbose to include local paths, scores, and match reasons.

Installation

Install from GitHub with Codex:

$skill-installer install https://github.com/in-asanz/Codex-Chat-Search

Install with the cross-agent skills CLI:

npx skills add in-asanz/Codex-Chat-Search -g -a codex -y

Use the branch URL while testing this release before it is merged to main:

npx skills add "https://github.com/in-asanz/Codex-Chat-Search.git#codex/prepare-official-skill-release" -g -a codex -y

For SkillsMP and skills.sh discovery, keep this repository public with SKILL.md at the repository root.

For local development, place this directory under your user skills folder:

~/.codex/skills/codex-chat-search/

Restart Codex after installation if the skill does not appear immediately.

Expected skill layout:

codex-chat-search/
  SKILL.md
  README.md
  LICENSE
  agents/
    openai.yaml
  references/
  scripts/
  tests/

This is not packaged as a Python library. The bundled Python script is a helper used by the skill.

Official release checklist

Before publishing a stable version:

• Confirm SKILL.md has only name and description frontmatter.
• Confirm agents/openai.yaml describes the same workflow as SKILL.md.
• Keep generated files, real Codex history, and local caches out of git.
• Run validation and tests from this directory:

python <path-to-skill-creator>\scripts\quick_validate.py .
python -m py_compile scripts\find_codex_conversations.py
python -m unittest discover -s tests
python scripts\find_codex_conversations.py --help

• Publish from a public repository URL that points directly at this skill folder, or tag the release and install from that tag URL.

Privacy

The tool reads local Codex history. Default text and JSON output avoid local file paths and debug scores. Use --verbose only when you need to disambiguate results.

Tests use synthetic fixtures only. Do not commit real conversation history.

Development

Run the validation commands:

python -m py_compile scripts\find_codex_conversations.py
python -m unittest discover -s tests
python scripts\find_codex_conversations.py --help

The GitHub Actions workflow in .github/workflows/ci.yml runs the same checks on Linux, Windows, and macOS across supported Python versions.

Publishing Notes

This project is licensed under the MIT License. Review the copyright holder in LICENSE before publishing under an organization or different owner name.