Codex Sessions Manager

intent

use this skill to inspect, search, export, verify, clean up, delete, restore, or purge local codex sessions stored under a codex root (default: ~/.codex). run it when the user wants to work with codex conversation history instead of the current live conversation. the skill provides both an MCP server (preferred) and a CLI fallback for session management operations including preview-only modes, recoverable trash deletion, and permanent purge.

inputs

codex root directory

• default: ~/.codex
• override: pass --root <path-to-codex-root> to all CLI commands or root param to MCP tools
• required: user must have read/write access to the target directory

MCP server availability

• env var: CODEX_SESSIONS_MCP (optional, indicates MCP server is running)
• setup: if using MCP, ensure the codex-sessions MCP server is configured in the current agent session
• fallback: if MCP is unavailable or blocked, CLI commands execute instead

CLI tool installation

• npm package: codex-sessions-manager
• install: npm install -g codex-sessions-manager
• provides commands: codex-sessions and codex-sessions-mcp
• dev alternative: clone repo, run npm install && npm run build, then use node dist/cli/index.js from repo root

session identifiers

• format: unique session ID (string) or trash ID for trash operations
• obtain: from list_sessions, list_trash, or list_projects calls

date/time filters (CLI and MCP)

• formats: date-only (YYYY-MM-DD, interpreted as local calendar day) or timezone-aware ISO 8601 datetime
• reject: timezone-less datetime strings (e.g., "2026-04-01T12:00:00" without Z or offset)
• options: updatedAfter, updatedBefore, createdAfter, createdBefore

project names or paths (optional)

• used by: list_sessions --project TEXT or MCP list_sessions(project=TEXT)
• enables: filter sessions by assigned project

procedure

step 1: inspect the codex root (safety check)

input: codex root path (default ~/.codex)

action: run MCP inspect_root or CLI doctor before any destructive operation (delete, restore, purge, cleanup).

MCP:

inspect_root(root="~/.codex")

CLI:

codex-sessions doctor --root ~/.codex
codex-sessions doctor --root ~/.codex --json

output: status report (OK, missing, or warning states). list of sessions, projects, trash entries, and global-state references. no chat content in output.

edge case: if warnings appear, report them to user and do not proceed with destructive operations until user confirms understanding.

step 2: list or search sessions

input: codex root, optional project name, optional time filters, optional grouping, optional limit

action: retrieve session list with metadata (ID, updated time, size, project, status, title).

prefer MCP:

list_sessions(root="~/.codex", limit=20)
list_sessions(root="~/.codex", project="my-project")
list_sessions(root="~/.codex", groupBy="project")
list_sessions(root="~/.codex", updatedAfter="2026-04-01", updatedBefore="2026-04-30")

fall back to CLI:

codex-sessions list --root ~/.codex --limit 20
codex-sessions list --root ~/.codex --project "my-project"
codex-sessions list --root ~/.codex --group-by project
codex-sessions list --root ~/.codex --updated-after 2026-04-01 --updated-before 2026-04-30

output: list of sessions with ID, updated timestamp, size bytes, project name, status, and readable title.

edge case (empty results): if no sessions match, report "no sessions found" with applied filters; suggest user broaden filter or check if codex root is correct.

step 3: list projects

input: codex root

action: retrieve project summary (name/path, session count, status distribution, latest updated time, total size).

prefer MCP:

list_projects(root="~/.codex")

fall back to CLI:

codex-sessions projects --root ~/.codex

output: project name/path, session count, counts by status, latest updated timestamp, total size bytes.

step 4: get or show a single session

input: codex root, session ID

action: retrieve full session metadata and summary (do not output full chat transcript).

prefer MCP:

get_session(root="~/.codex", sessionId="SESSION_ID")

fall back to CLI:

codex-sessions show SESSION_ID --root ~/.codex

output: session ID, created/updated timestamps, project, status, size, title, and summary of conversation (no raw chat content).

edge case (not found): if session ID does not exist, report "session not found"; suggest user search with list_sessions first.

step 5: export session to backup file

input: codex root, session ID, output file path

action: export session as JSON backup.

prefer MCP:

export_session_backup(root="~/.codex", sessionId="SESSION_ID")

fall back to CLI:

codex-sessions export SESSION_ID --root ~/.codex --output ./backup.json

output: JSON file written to disk. include file path and file size in success response.

edge case (network timeout): if export hangs, kill the process after 30 seconds and report "export timed out; try again or use smaller session".

step 6: preview delete (non-destructive)

input: codex root, one or more session IDs, trash flag (true for recoverable, false/absent for permanent)

action: show which sessions will be deleted and whether delete is permanent or recoverable; do not execute deletion.

prefer MCP:

preview_delete_sessions(root="~/.codex", sessionIds=["ID1", "ID2"], trash=false)
preview_delete_sessions(root="~/.codex", sessionIds=["ID1", "ID2"], trash=true)

fall back to CLI:

codex-sessions delete ID1 ID2 --root ~/.codex
codex-sessions delete ID1 ID2 --root ~/.codex --trash

output: list of sessions to be deleted, delete type (permanent or trash), and file/row counts affected. do not include chat content.

edge case (multiple sessions): if user selected >10 sessions, confirm count and ask user to review before proceeding to step 7.

step 7: execute delete (with confirmation)

input: codex root, one or more session IDs, trash flag, confirmation flag (true to execute)

action: delete sessions permanently or move to trash (recoverable). only execute if confirm=true (MCP) or --yes flag (CLI).

prefer MCP:

delete_sessions(root="~/.codex", sessionIds=["ID1"], trash=false, confirm=true)
delete_sessions(root="~/.codex", sessionIds=["ID1"], trash=true, confirm=true)

fall back to CLI:

codex-sessions delete ID1 --root ~/.codex --yes
codex-sessions delete ID1 --root ~/.codex --trash --yes

output: confirmation of deleted session IDs, type (permanent or trash), and count of files/rows removed.

edge case (trash conflicts): if session already exists in trash, report conflict and skip; do not overwrite existing trash entry.

step 8: list trash entries

input: codex root

action: retrieve trash contents (trashed session IDs, timestamps, sizes).

prefer MCP:

list_trash(root="~/.codex")

fall back to CLI:

codex-sessions trash-list --root ~/.codex

output: list of trash entries with session ID, trashed timestamp, size, and project.

edge case (empty trash): if no trash entries, report "trash is empty".

step 9: restore from trash

input: codex root, trash ID or original session ID, confirmation flag

action: restore trashed session to live storage. only execute if confirm=true (MCP) or --yes flag (CLI).

prefer MCP:

restore_sessions(root="~/.codex", trashIds=["TRASH_ID"], confirm=true)

fall back to CLI:

codex-sessions restore TRASH_ID --root ~/.codex --yes

output: confirmation of restored session ID, restored timestamp, and file/row counts written.

edge case (live conflict): if a live session with the same ID already exists, restore refuses the operation and reports "live session already exists"; no force overwrite mode available.

edge case (SQLite key conflict): if SQLite row with same key exists, restore refuses operation; report conflict and suggest user verify or inspect root first.

step 10: purge trash entry (permanent)

input: codex root, trash ID, confirmation flag

action: permanently delete trash entry (cannot be recovered). only execute if confirm=true (MCP) or --yes flag (CLI). does not touch live sessions.

prefer MCP:

purge_trash(root="~/.codex", trashIds=["TRASH_ID"], confirm=true)

fall back to CLI:

codex-sessions purge TRASH_ID --root ~/.codex --yes

output: confirmation of purged trash ID and file counts removed.

edge case (not in trash): if trash ID not found, report "trash entry not found"; suggest user list trash first.

step 11: cleanup session JSONL indexes

input: codex root, one or more session IDs, confirmation flag

action: rewrite session_index.jsonl for selected sessions. does not delete raw files or SQLite rows. only execute if confirm=true (MCP) or --yes flag (CLI).

prefer MCP:

cleanup_session_indexes(root="~/.codex", sessionIds=["ID1"], confirm=true)

fall back to CLI:

codex-sessions cleanup-index ID1 --root ~/.codex --yes

output: confirmation of sessions reindexed, files rewritten, and warnings resolved.

edge case (stale index): if index is already clean, report "no stale entries found" and skip rewrite.

step 12: cleanup stale JSONL indexes globally

input: codex root, confirmation flag

action: scan and rewrite session_index.jsonl and history.jsonl to remove stale entries. only execute if confirm=true (MCP) or --yes flag (CLI).

prefer MCP:

cleanup_stale_indexes(root="~/.codex", confirm=true)

fall back to CLI:

codex-sessions cleanup-stale --root ~/.codex --yes

output: count of stale entries removed, files rewritten, and warnings resolved.

edge case (no stale entries): if no stale entries found, report "no cleanup needed".

step 13: verify sessions fully removed

input: codex root, one or more session IDs

action: check whether session is completely removed from files, JSONL rows, SQLite rows, shell snapshots, and global-state references. report any remaining artifacts.

prefer MCP:

verify_sessions(root="~/.codex", sessionIds=["ID1"])

fall back to CLI:

codex-sessions verify ID1 --root ~/.codex

output: verification status (fully removed, partial artifacts, or warnings). list any remaining files, JSONL rows, SQLite rows, shell snapshots, or global-state references by key path.

edge case (unknown global-state refs): if unknown global-state keys exist, report key path and count only (not full content). treat as warnings; do not edit or delete automatically.

decision points

if MCP server is available in agent session:

• use MCP tools (inspect_root, list_sessions, get_session, delete_sessions with confirm=true, etc.).
• MCP is the preferred path because it does not require shell execution or package installation.

else (MCP unavailable or blocked):

• fall back to CLI commands (codex-sessions list, codex-sessions delete ... --yes, etc.).
• if CLI is not installed globally, use node dist/cli/index.js from cloned repo instead.

if user wants to delete sessions:

• always run step 1 (inspect root) first to detect warnings.
• always run step 6 (preview delete) to show what will be deleted.
• ask user to confirm before executing step 7 unless user has already explicitly approved ("yes, delete").
• prefer recoverable trash deletion (trash=true in MCP, --trash --yes in CLI) over permanent delete.

if user wants to restore from trash:

• run step 8 (list trash) to find the correct trash ID.
• run step 9 (restore) with confirm=true (MCP) or --yes (CLI).
• if restore fails with "live session already exists", report conflict and stop; no force overwrite mode.

if user wants to purge trash:

• run step 8 (list trash) to identify trash ID.
• run step 10 (purge) with confirm=true (MCP) or --yes (CLI).
• purge only removes trash entry, never touches live sessions.

if user asks about side conversations:

• treat parent thread and side child thread as separate sessions.
• search, export, delete, restore by child thread ID only.
• if user wants to handle parent and side conversations together, identify all child IDs first, preview all selected IDs in step 6, then execute step 7 with all IDs.

if user wants to filter sessions by time:

• accept date-only (YYYY-MM-DD) interpreted as local calendar day, or ISO 8601 with timezone.
• reject timezone-less datetime strings; ask user to add Z or offset (e.g., "2026-04-01T12:00:00Z").

if verify, doctor, or inspect_root reports warnings:

• report warnings to user and do not claim root is fully clean.
• do not output chat content in warning reports.
• if unknown global-state keys exist, report key path and count only.

if session not found:

• suggest user run step 2 (list sessions) to search with filters (project, time range, limit).

if trash entry conflicts with live session (same ID):

• report "session already exists in live storage"; restore refuses operation.
• suggest user delete the live session first, then restore.

if cleanup-index or cleanup-stale finds no stale entries:

• report "no cleanup needed" and skip rewrite.

output contract

list operations: JSON array or formatted table with columns: session ID, updated timestamp (ISO 8601), size bytes, project name, status, readable title. example:

ID: abc123 | Updated: 2026-04-15T14:22:00Z | Size: 45KB | Project: my-project | Status: active | Title: "Debug session"

project operations: JSON array or formatted table with columns: project name/path, session count, status distribution (e.g., "10 active, 2 archived"), latest updated timestamp, total size bytes.

show operations: structured object with: session ID, created timestamp, updated timestamp, project, status, size bytes, readable title, conversation summary (no raw chat content).

export operations: JSON file written to specified output path. file contains full session transcript. response includes output file path and file size bytes.

preview delete / verify operations: plain text or JSON report with: list of session IDs, operation type (permanent delete / trash move / restore / purge), affected file count, affected JSONL row count, affected SQLite row count. include shell snapshot refs and global-state refs if present. no chat content.

delete / restore / purge / cleanup operations: confirmation message with: operation type, session IDs affected, timestamp of operation, file/row counts changed. example:

✓ Moved 2 sessions to trash: abc123, def456 | Files: 8 | Rows: 24 | Time: 2026-04-15T14:22:00Z

trash operations: list with: trash ID, original session ID, trashed timestamp, size bytes, project name. or confirmation of restore/purge with same format as delete/restore/purge output above.

error responses: plain text error message with: operation attempted, error code, root cause, suggested next step. example:

Error: Session not found (session_id=xyz789). Run 'list_sessions' to search by project or time range.

outcome signal

user knows the skill worked when:

• list/search: user sees sessions matching their filter criteria (project, time range, limit) with all metadata columns visible.
• show: user sees full session metadata and conversation summary without needing to open raw files.
• export: file is written to disk and user can open the JSON backup in an editor.
• preview delete: user sees exactly which sessions will be deleted, how many files/rows are affected, and whether delete is permanent or recoverable, before any destructive action.
• delete: user receives confirmation of moved or deleted sessions with timestamp and count of changes, and trash list (step 8) shows the trashed session if --trash was used.
• restore: previously trashed session reappears in live session list (verify with step 2) and matches the original session ID.
• purge: trash entry disappears from trash list (step 8) and verify (step 13) confirms no artifacts remain.
• cleanup: stale JSONL entries are removed and user can verify with inspect_root (step 1) that warnings are resolved.
• verify: user receives a report showing whether session is fully