// Finds Codex session coordinates by id, title, repo path, rollout path, or topic. Use when a user or another skill needs thread metadata and rollout paths for its own review.
| name | codex-session-finder |
| description | Finds Codex session coordinates by id, title, repo path, rollout path, or topic. Use when a user or another skill needs thread metadata and rollout paths for its own review. |
Find the relevant local Codex session and return the session coordinates. This skill locates the thread; it does not summarize, judge, or extract the important parts of the conversation unless the user explicitly asks for inspection.
Codex keeps local session state under the user's Codex home directory.
state_5.sqlite stores thread metadata, including id, title, workspace path, timestamps, archive state, branch, commit, tokens_used, and rollout path.session_index.jsonl is a lightweight session index. It is useful for lookup, but SQLite is the stronger source of truth when both exist.sessions/ contains current rollout files.archived_sessions/ contains archived rollout files.Accept any of these:
If the input is vague, search metadata first and return likely candidates rather than guessing silently.
Use this only when the user asks to inspect, review, debug, or hand off the session content. Do not export turns for a plain lookup.
Write a temporary turn-by-turn export under /tmp or the system temp directory, never inside the target repository. Prefer Markdown or JSONL with one entry per conversation turn, preserving role, timestamp when available, and a short content preview or full content depending on the user's request.
Return the temp export path with the session locator:
Export:
- turns path: /tmp/<file>
Keep the chat content out of the assistant response unless the user explicitly asks for excerpts. A temp export lets the next agent search, summarize, or review the thread independently without making the locator output noisy.
Use this mode when another skill needs to avoid active Codex worktrees, coordinate multiple worktrees, or understand which local branches are currently being edited.
Query active, non-archived sessions first:
sqlite3 -header -column ~/.codex/state_5.sqlite \
"select id, title, cwd, datetime(created_at,'unixepoch') as created_at,
datetime(updated_at,'unixepoch') as updated_at,
git_branch, git_sha, tokens_used, rollout_path
from threads
where archived = 0
order by updated_at desc;"
For a specific repo or worktree family, filter by cwd:
sqlite3 -header -column ~/.codex/state_5.sqlite \
"select id, title, cwd, datetime(updated_at,'unixepoch') as updated_at,
git_branch, git_sha, rollout_path
from threads
where archived = 0
and cwd like '%/vitehub%'
order by updated_at desc;"
Before selecting optional columns in a newer or older Codex install, inspect the schema:
sqlite3 ~/.codex/state_5.sqlite '.schema threads'
Use tokens_used for token counts in current schemas; do not select token_count unless the schema actually contains it.
Report active worktrees as off-limits for mutating follow-up tasks unless the user explicitly says to use that session's worktree.
Query state_5.sqlite.
threads table.Check session_index.jsonl when SQLite does not resolve the request.
Search rollout files only when needed to identify the session.
sessions/ and archived_sessions/.Return a compact metadata report. The result is a locator, not a narrative or review.
For one clear match, especially an exact thread id or rollout path match, use:
Found session:
- id:
- title:
- cwd:
- created:
- updated:
- archived:
- branch:
- git sha:
- tokens used:
- rollout path:
Do not include "Why this match", confidence language, or an evidence slice for exact or otherwise unambiguous matches. The metadata is the output.
Include fields that help another agent route its own follow-up work: id, title, cwd, timestamps, archive state, branch, commit, token count, and rollout path. Do not decide which conversation turns are "important"; a follow-up agent should inspect the rollout file on its own when it needs content.
Include a short "Match basis" only when the input was vague, multiple candidates are plausible, or the lookup used fallback sources:
Match basis:
- <short factual reason, such as title/path/token match>
Other candidates:
- <include only when ambiguity matters>
Include an "Evidence slice" only when the user asks to inspect what happened in the session or metadata alone cannot identify the right session. Keep excerpts minimal and summarize private content when possible.
If a temp turn export was requested, include only the export path in the main response. Do not duplicate the exported content in the response.
For active worktree lookups, use:
Active sessions:
1. <id> - <title>
- cwd:
- branch:
- updated:
- rollout path:
Likely safe/inactive related worktrees:
- ... <!-- only if discovered from metadata and clearly archived/inactive -->
Use guidance:
- Treat active session worktrees as read-only/off-limits unless the user explicitly opts in.
/tmp are allowed only when requested.Creates or revises one portable agent skill with concise routing, progressive disclosure, and clear safety boundaries. Use when the user wants to write, clean up, or restructure a skill.
Reviews recent Codex sessions for repeated agent failures and skill improvements. Use for daily/weekly retrospectives, skill audits, agent-pattern analysis, or cleanup recommendations.
Clarifies fuzzy direction into durable memory and issue-shaping handoff. Use when the user wants to turn an idea, conversation, ADR, PRD, or prior session into clear agent-ready work.
Gathers internal or external evidence for one decision and returns sourced patterns. Use when design, planning, retrospectives, or architecture depends on research before deciding.
Skips obvious branches inside grilling sessions by stating the assumed answer and moving on. Use when the user says fast-forward, skip, obvious, same as me, or next unclear area.
Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates agent-owned documentation under `.agents/` inline as decisions crystallise. Use when the real task is defining purpose, scope, structure, canonical terms, capture/refinement criteria, or other durable decisions for the project.