skills/codex-thread-history-search

SKILL.md

name	codex-thread-history-search
description	Search earlier turns in Codex Desktop tasks with read-only history access and tool-side filtering. Use when recovering prior decisions, commands, procedures, or context from the current or another Codex task without loading whole histories into the model context.

Codex Thread History Search

Recover relevant evidence from persisted Codex task history while keeping model-context use proportional to the answer.

Boundaries

• Treat the operation as read-only. Do not resume, fork, message, archive, or otherwise mutate a task.
• Prefer documented Codex thread APIs over rollout JSONL, SQLite state, session files, or equivalent harness storage.
• Do not use this workflow for ordinary repository search, web research, or facts already present in the visible conversation.
• Do not silently inspect internal storage. Use that fallback only after explaining the proposed source and scope and receiving explicit user permission.

Resolve The Target

1. Use an explicit task URL or thread ID when supplied.
2. Otherwise use host-provided current-task metadata when available.
3. If necessary, call list_threads with a small limit or discriminating query and match the working directory, title, recency, and status. Do not guess when multiple tasks remain plausible.

Choose The Shortest Viable Path

Use this fixed escalation order. Stop at the first level that can answer the question; do not compare every possible route in advance.

1. Use a native occurrence-search capability when the harness exposes one. Retrieve only the matching turn detail needed to answer.
2. Otherwise page through documented thread history and filter inside the tool execution environment.
3. Otherwise use a documented full-session read or export facility and filter its result in the tool process before emitting excerpts.
4. If no documented route is usable, report the limitation and ask permission to search the harness's persisted rollout, session files, database, or equivalent storage in read-only mode.

Discover available capabilities from the current tool registry and their descriptions rather than assuming one permanent wrapper name. If a previously available handler is missing, rediscover it once; a desktop-app restart may restore a missing handler.

Read Efficiently

• For one recent page, a direct read_thread call is acceptable.
• For older or uncertain history, call read_thread from functions.exec and filter inside the JavaScript isolate. Nested tool results do not enter model context unless emitted with text(...).
• Request at most 10 turns per page, set includeOutputs: false, and follow page.nextCursor toward older turns.
• Search case-insensitively with a compact set of terms and meaningful variants, including translated terminology, command names, paths, and error fragments when relevant.
• Emit only matching excerpts with enough surrounding text to identify the decision or procedure. Never emit every fetched page merely to inspect it.
• Stop when the evidence is sufficient, history is exhausted, or a reasonable page bound is reached. Say when the search was bounded or inconclusive.

A typical deep-search orchestration has this shape:

let cursor;
for (let pageIndex = 0; pageIndex < pageLimit; pageIndex++) {
  const raw = await tools.codex_app__read_thread({
    threadId,
    cursor,
    turnLimit: 10,
    includeOutputs: false,
  });
  const page = typeof raw === "string" ? JSON.parse(raw) : raw;
  const serialized = JSON.stringify(page.turns ?? []);
  const excerpts = findRelevantExcerpts(serialized, terms);
  for (const excerpt of excerpts) text(excerpt);
  if (excerpts.length && evidenceIsSufficient(excerpts)) break;
  cursor = page.page?.nextCursor;
  if (!cursor) break;
}

The helper names are illustrative. Implement small local matching and excerpt logic in the isolate; do not create repository files for an ordinary history search.

Search Persisted Storage By Permission

When documented APIs cannot answer the question:

1. Identify the likely storage source and state whether it is documented or an unstable implementation detail.
2. Tell the user what will be searched and whether the requested scope may include tool outputs or other sensitive records, then obtain explicit permission.
3. Prefer documented session files over internal databases. Use read-only commands, streaming parsers, or immutable/read-only database access; never resume or rewrite the session.
4. It is acceptable to scan a complete persisted record in the tool process. Emit only compact matches and necessary neighboring text into model context.
5. If access still fails, report the verified limitation and provide clearly labeled hypotheses about the cause and the next plausible route.

Retrieve Detail In Two Passes

Start from summaries and messages. If the answer specifically depends on an exact command output or truncated tool result, re-read only the matching page with includeOutputs: true and a conservative maxOutputCharsPerItem. Keep the first-pass terms or turn identity so the second pass does not broaden into a full-history dump.

Report The Result

• Distinguish a verbatim recovered instruction from a present-day synthesis.
• Preserve exact commands, paths, version numbers, and stopping conditions when they matter.
• Mention the source task or approximate turn position when useful, without exposing opaque internal metadata unnecessarily.
• If later evidence supersedes earlier advice, present the latest verified procedure and briefly note the supersession.