Codex Sessions Manager

Overview

This skill manages local Codex sessions through the codex-sessions toolkit.

Use it when the user wants to work with local Codex conversation history instead of the current live chat thread.

Prerequisites

This skill requires the CLI to be built from this repository.

Why: The skill file (SKILL.md) is read by the AI agent. When the AI executes CLI commands from this file, it runs them in the current working directory — not the skill directory. So relative paths like dist/cli/index.js won't work unless the CLI is globally available.

Option 1 — Global install (recommended):

cd /path/to/where/you/cloned/codex-sessions-manager
npm install
npm run build
npm install -g .       # makes `codex-sessions` available everywhere

Then use codex-sessions instead of node dist/cli/index.js in commands below.

Option 2 — Keep local, use full path:

cd /path/to/where/you/cloned/codex-sessions-manager
npm install
npm run build

Then replace node dist/cli/index.js below with the full path, e.g.: node /home/you/codex-sessions-manager/dist/cli/index.js

When To Use

Use this skill for requests like:

• "列出我最近的 Codex 对话"
• "看一下这条 session 的详情"
• "导出这个会话"
• "删除这几个会话"
• "先预览删除会影响什么"
• "清理失效索引"
• "验证这条会话还有没有残留"

Do not use this skill for:

• generic ChatGPT history questions
• Claude Code session management
• editing the current conversation

Execution Order

1. Prefer MCP first

If the codex-sessions MCP server is available in the current Codex session, use these tools:

• list_sessions
• get_session
• export_session_backup
• preview_delete_sessions
• delete_sessions (requires confirm=true to execute; without it, returns a preview)
• cleanup_session_indexes
• cleanup_stale_indexes
• verify_sessions

2. Fall back to CLI when MCP is unavailable

If you installed globally (npm install -g .), use codex-sessions:

codex-sessions list --root ~/.codex --limit 20
codex-sessions show <session-id> --root ~/.codex
codex-sessions export <session-id> --root ~/.codex --output ./backup.json
codex-sessions delete <session-id...> --root ~/.codex
codex-sessions delete <session-id...> --root ~/.codex --yes
codex-sessions cleanup-index <session-id...> --root ~/.codex
codex-sessions cleanup-stale --root ~/.codex
codex-sessions verify <session-id...> --root ~/.codex

If you didn't install globally, replace codex-sessions with the full path to dist/cli/index.js.

Safety Rules

• Treat delete as destructive. Always preview first unless the user has already explicitly confirmed deletion.
• delete without --yes is the preferred safe preview path in CLI mode.
• cleanup-index only removes JSONL traces; it does not delete raw files or SQLite rows.
• cleanup-stale only removes stale index records.
• When the user asks to delete sessions, echo back the session IDs you are about to delete before executing if there is any ambiguity.

Response Style

• For list requests: show session ID, updated time, size, and a readable title.
• For show requests: summarize the session and include the key metadata.
• For delete requests: explain whether this is preview-only or actual deletion.
• For verify requests: report whether files, JSONL rows, and SQLite rows still remain.

Quick Examples

List recent archived sessions

Use MCP list_sessions with status=archived and limit=5.

CLI fallback:

node dist/cli/index.js list --root ~/.codex --status archived --limit 5

Preview deleting a session

Use MCP preview_delete_sessions.

CLI fallback:

node dist/cli/index.js delete 019d5240 --root ~/.codex

Actually delete confirmed sessions

Use MCP delete_sessions only after clear user confirmation, and pass confirm=true.

CLI fallback:

node dist/cli/index.js delete 019d5240 019d3de0 --root ~/.codex --yes