# Codex Chat Search

> Search local Codex conversation history on disk and identify the most likely past session by date, thread name, remembered phrases, or topic hints. Use when the user asks to find, locate, recover, identify, or search a previous Codex chat, session, or conversation from local history.

- Skill: `in-asanz/codex-chat-search` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add in-asanz/codex-chat-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/in-asanz/codex-chat-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: in-asanz (https://skillmd.com/u/in-asanz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/in-asanz/codex-chat-search

---


# Codex Chat Search

## Overview

Search only local Codex history under `~/.codex`.
Prioritize fast narrowing by date and `thread_name`, then inspect matching session files to produce a simple answer.
The bundled script is offline-only and should not send conversation contents outside the machine.

## Workflow

1. Infer as many search hints as possible from the current conversation before asking anything.
2. Treat `today`, `yesterday`, and similar phrases as exact calendar dates before searching.
3. Search `session_index.jsonl` first.
4. Use session JSONL files under `sessions/` and `archived_sessions/` to enrich or recover candidates when the index is insufficient.
5. Prefer evidence from user messages over diffs, logs, long code blocks, and developer instructions.
6. Return the best matches in a simple format with:
   - conversation name
   - date and time
   - date and time of the last user message
   - short description

## Ask Only When Needed

Ask the user one concise question about what the conversation was about only if the current thread does not already provide enough usable hints such as:

- approximate date
- remembered phrase
- topic
- file, tool, or repo mentioned

If you ask, request the smallest missing clue.

## Output Rules

Keep the final answer simple.
For each candidate, provide:

- `Nombre`
- `Fecha`
- `Ultimo mensaje usuario`
- `Descripcion`

Include the local file path only when it materially helps disambiguate or when the user asks for it.
Use script `--verbose` output when path, score, or match reasons are needed for disambiguation.

## Quick Start

Use the bundled script first:

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

Useful variations:

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

## Search Heuristics

- Give the highest weight to exact phrase matches in `thread_name`.
- Next prefer exact phrase matches in user-authored messages.
- Then use token matches in `thread_name`, first user message, and later user messages.
- Treat accented and unaccented text as equivalent for search matching.
- Use date filters early to reduce noise.
- If the user says the chat was from Codex, do not search outside local Codex history.

## Resources

### scripts/

- `scripts/find_codex_conversations.py`: search `session_index.jsonl` and `sessions/**/*.jsonl`, score candidates, and emit structured results.

### references/

- `references/codex-history-layout.md`: local history locations and file roles.
- `references/search-playbook.md`: fallback tactics for weak or ambiguous search hints.