ClawHub

Codex Sessions Manager

Use this skill when the user wants to inspect, search, export, verify, clean up, delete, restore, or purge local Codex sessions stored under a Codex root such as ~/.codex.

Audits

Pass
ClawScanPass

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install codex-sessions-manager

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 conversation.

This repository provides:

  • a Node / TypeScript CLI
  • a local stdio MCP server
  • this Skill entrypoint

The project is not a UI product, TUI, detail page, incremental scanner, or automatic cleanup service.

Setup

Install the CLI before using fallback commands:

npm install -g codex-sessions-manager

This provides:

codex-sessions
codex-sessions-mcp

For local development, build the repository first:

cd <path-to-codex-sessions-repo>
npm install
npm run build

The default Codex root is:

~/.codex

Use --root <path-to-codex-root> when working with another Codex root.

When To Use

Use this skill for requests like:

  • "List my recent Codex sessions"
  • "Find sessions for this project"
  • "Show this session"
  • "Find side conversations for this session"
  • "Export this session"
  • "Preview deleting these sessions"
  • "Move these sessions to trash"
  • "Restore this trash entry"
  • "Purge this trash entry"
  • "Verify whether this session is fully removed"
  • "Inspect the Codex root before deleting or restoring"
  • "Clean stale JSONL indexes"

Do not use this skill for:

  • generic ChatGPT history questions
  • non-Codex chat clients
  • editing the current live conversation
  • automatic cleanup schedules
  • provider or model repair

Preferred Order

1. Prefer MCP first

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

  • inspect_root
  • list_sessions
  • list_projects
  • get_session
  • export_session_backup
  • preview_delete_sessions
  • delete_sessions (requires confirm=true to execute; pass trash=true for recoverable deletion)
  • list_trash
  • restore_sessions (requires confirm=true)
  • purge_trash (requires confirm=true)
  • cleanup_session_indexes (requires confirm=true to rewrite JSONL indexes)
  • cleanup_stale_indexes (requires confirm=true to rewrite JSONL indexes)
  • verify_sessions

Use MCP tools first. CLI is the fallback when MCP is unavailable or blocked.

For session lookup, narrow in this order:

  1. project
  2. status
  3. updated / created time
  4. preview or get_session

For project-aware listing, pass project to list_sessions or use groupBy="project".

For time filters, pass updatedAfter, updatedBefore, createdAfter, or createdBefore. Date-only filters use the local calendar day. Timezone-less datetime strings must be rejected.

2. Fall back to CLI

Prefer the installed CLI:

codex-sessions doctor --root <path-to-codex-root>
codex-sessions doctor --root <path-to-codex-root> --json
codex-sessions list --root <path-to-codex-root> --limit 20
codex-sessions list --root <path-to-codex-root> --project TEXT
codex-sessions list --root <path-to-codex-root> --group-by project
codex-sessions list --root <path-to-codex-root> --updated-after 2026-04-01 --updated-before 2026-04-30
codex-sessions projects --root <path-to-codex-root>
codex-sessions show <session-id> --root <path-to-codex-root>
codex-sessions export <session-id> --root <path-to-codex-root> --output ./backup.json
codex-sessions delete <session-id...> --root <path-to-codex-root>
codex-sessions delete <session-id...> --root <path-to-codex-root> --yes
codex-sessions delete <session-id...> --root <path-to-codex-root> --trash
codex-sessions delete <session-id...> --root <path-to-codex-root> --trash --yes
codex-sessions trash-list --root <path-to-codex-root>
codex-sessions restore <trash-id-or-session-id> --root <path-to-codex-root>
codex-sessions restore <trash-id-or-session-id> --root <path-to-codex-root> --yes
codex-sessions purge <trash-id-or-session-id> --root <path-to-codex-root>
codex-sessions purge <trash-id-or-session-id> --root <path-to-codex-root> --yes
codex-sessions cleanup-index <session-id...> --root <path-to-codex-root>
codex-sessions cleanup-index <session-id...> --root <path-to-codex-root> --yes
codex-sessions cleanup-stale --root <path-to-codex-root>
codex-sessions cleanup-stale --root <path-to-codex-root> --yes
codex-sessions verify <session-id...> --root <path-to-codex-root>

When working from a cloned repository instead, run commands from the built repository:

cd <path-to-codex-sessions-repo>

Commands:

node dist/cli/index.js doctor --root <path-to-codex-root>
node dist/cli/index.js doctor --root <path-to-codex-root> --json
node dist/cli/index.js list --root <path-to-codex-root> --limit 20
node dist/cli/index.js list --root <path-to-codex-root> --project TEXT
node dist/cli/index.js list --root <path-to-codex-root> --group-by project
node dist/cli/index.js list --root <path-to-codex-root> --updated-after 2026-04-01 --updated-before 2026-04-30
node dist/cli/index.js projects --root <path-to-codex-root>
node dist/cli/index.js show <session-id> --root <path-to-codex-root>
node dist/cli/index.js export <session-id> --root <path-to-codex-root> --output ./backup.json
node dist/cli/index.js delete <session-id...> --root <path-to-codex-root>
node dist/cli/index.js delete <session-id...> --root <path-to-codex-root> --yes
node dist/cli/index.js delete <session-id...> --root <path-to-codex-root> --trash
node dist/cli/index.js delete <session-id...> --root <path-to-codex-root> --trash --yes
node dist/cli/index.js trash-list --root <path-to-codex-root>
node dist/cli/index.js restore <trash-id-or-session-id> --root <path-to-codex-root>
node dist/cli/index.js restore <trash-id-or-session-id> --root <path-to-codex-root> --yes
node dist/cli/index.js purge <trash-id-or-session-id> --root <path-to-codex-root>
node dist/cli/index.js purge <trash-id-or-session-id> --root <path-to-codex-root> --yes
node dist/cli/index.js cleanup-index <session-id...> --root <path-to-codex-root>
node dist/cli/index.js cleanup-index <session-id...> --root <path-to-codex-root> --yes
node dist/cli/index.js cleanup-stale --root <path-to-codex-root>
node dist/cli/index.js cleanup-stale --root <path-to-codex-root> --yes
node dist/cli/index.js verify <session-id...> --root <path-to-codex-root>

Safety Rules

  • Run MCP inspect_root or CLI doctor before delete, restore, purge, or cleanup when Codex storage may have changed.
  • Treat delete, restore, purge, and cleanup as dangerous write paths.
  • Always preview before destructive actions unless the user has already clearly confirmed execution.
  • CLI delete without --yes is preview-only.
  • MCP delete_sessions without confirm=true is preview-only.
  • Permanent delete remains available for compatibility.
  • Prefer recoverable deletion with CLI --trash --yes or MCP trash=true, confirm=true.
  • delete --trash without --yes only previews moving sessions to trash.
  • restore and purge require --yes in CLI mode.
  • MCP restore_sessions and purge_trash require confirm=true.
  • Restore refuses live session conflicts and SQLite key conflicts. There is no force overwrite mode.
  • purge removes only the trash entry and must not touch live sessions.
  • cleanup-index and cleanup-stale rewrite session_index.jsonl and history.jsonl. They do not delete raw files or SQLite rows, but they still require --yes.
  • MCP cleanup_session_indexes and cleanup_stale_indexes require confirm=true to rewrite JSONL indexes.
  • Global-state cleanup is limited to known structured keys.
  • Unknown global-state references are warnings only. Do not edit or delete unknown keys automatically.
  • If verify, doctor, or inspect_root reports warnings, tell the user. Do not claim the root is fully clean.
  • Do not output chat content when reporting doctor, verify, or global-state warnings.

Side Conversations

Codex /side creates an ephemeral side conversation with a separate transcript. In local storage, it can appear as a separate child thread linked to a parent thread.

When a user asks about side conversations:

  • Treat the parent thread and side child thread as separate sessions with separate transcripts.
  • Search, show, export, delete, trash, restore, or verify the child thread by its own session ID.
  • Do not assume deleting, exporting, or summarizing a parent thread also handles its side child threads.
  • If the user wants a parent thread and its side conversations handled together, identify the child thread IDs first, preview all selected IDs together, and only then run any confirmed write operation.
  • Current CLI/MCP behavior does not automatically recurse from parent to side child threads.

Response Style

  • For list requests: show session ID, updated time, size, project, status, and readable title.
  • For project requests: show project name/path, session count, status counts, latest updated time, and total size.
  • For show requests: summarize the session and include key metadata.
  • For side-conversation requests: distinguish parent thread ID and child thread ID, and say whether the requested action covers one or both.
  • For delete requests: explain whether this is preview-only, permanent delete, or recoverable trash delete.
  • For trash requests: distinguish moved to trash, restored, and purged.
  • For restore conflicts: explain that the live session already exists and identify conflicting surfaces when available.
  • For verify requests: report whether files, JSONL rows, SQLite rows, shell snapshots, global-state refs, or warnings remain.
  • For doctor / inspect requests: report OK, missing, and warning states without printing chat content.
  • For unknown global-state refs: report key path and count, not full global state content.

Non-Goals

Do not build or imply support for:

  • UI
  • TUI
  • detail pages
  • incremental project scanning
  • automatic stale cleanup
  • automatic trash purge
  • force overwrite restore
  • automatic editing of unknown global-state keys
  • non-Codex chat cleanup