codex-history-manager

Search, read, export, hand off, clone, move, or rebind local Codex history stored under ~/.codex. Use when the user wants to inspect past Codex sessions, bri...

Security Scan

The skill's files and runtime instructions are coherent with its declared purpose (local management of Codex history under ~/.codex); it performs local file and DB reads/writes and includes explicit dry-run/approval safeguards for dangerous edits.

Purpose & Capability

Name/description, README, SKILL.md, and the included Python scripts all focus on reading and mutating local Codex data under ~/.codex (state_5.sqlite and rollout JSONL). The requested/required resources (none) and provided code match the purpose; there are no unrelated credentials, network endpoints, or external services referenced.

Instruction Scope

Runtime instructions tell the agent to run the bundled CLI to search, export, clone/move, rebind provider metadata, and perform 'dangerous' history rewrites. The SKILL.md explicitly limits scope to ~/.codex and prescribes dry-run and explicit approval flows for destructive changes. This is coherent, but the skill does permit high-risk local modifications (rewriting transcript bodies) so users must follow the stated approval steps (plan → present changes in-chat → explicit approval → apply).

Install Mechanism

No install spec is provided (instruction-only at registry level), but the package includes Python scripts that can be executed directly. There are no external downloads or third-party install sources in the manifest. Running the CLI will execute local code included in the skill bundle.

Credentials

The skill requires no environment variables, no external credentials, and only accesses local Codex data paths (~/.codex) and a default backup directory inside the package tree. Requested access is proportional to the declared functionality. There are no unexplained SECRET/TOKEN/PASSWORD requirements.

Persistence & Privilege

The skill is not always-enabled and does not request elevated platform privileges. It does write backups and can mutate local files when run with --apply; those behaviors are documented in references/safety.md and guarded by dry-run and explicit-ack flags for dangerous edits.

Assessment

This tool appears to be what it says: a local CLI to inspect and manage Codex history under ~/.codex. Key precautions: (1) Review and run any destructive command with --dry-run first and inspect the generated plan file; (2) keep in mind apply-dangerous-edit can rewrite stored conversation text — follow the plan → present → explicit-approval → apply flow exactly; (3) backups are created by default under the package's backups/ directory—consider specifying --backup-root to a location you control; (4) the skill operates on local files only (no network calls in the included code), but these files may contain sensitive conversation data — only run it in a trusted local environment. If you want extra assurance, inspect the included scripts (scripts/codex_history_manager.py) before executing any write operations.

Use codex-history-manager when the task is about local Codex history, not general ChatGPT or web chat history.

Codex stores local history in two places:

• ~/.codex/state_5.sqlite for thread metadata
• ~/.codex/sessions/.../rollout-*.jsonl and ~/.codex/archived_sessions/... for event logs

The bundled CLI is the source of truth for reading and mutating that state:

• ./codex-history-manager ...

Default workflow

1. For discovery, start with search.
2. For context, use show-thread or handoff.
3. For exports, use export-thread.
4. For cross-workspace reuse, prefer clone-thread over move-thread.
5. For writes, run a dry run first, then rerun with --apply.
6. For history body rewrites, always do plan-dangerous-edit, show the warning and change list to the user, get explicit approval in chat, then run apply-dangerous-edit.

Core commands

• Search threads: ./codex-history-manager search --query "payments"
• Read one thread: ./codex-history-manager show-thread --id <thread-id>
• Export transcript: ./codex-history-manager export-thread --id <thread-id> --format markdown --output /tmp/thread.md
• Create a handoff note: ./codex-history-manager handoff --id <thread-id> --output /tmp/handoff.md
• Plan a dangerous history content rewrite: ./codex-history-manager plan-dangerous-edit --id <thread-id> --find "old" --replace "new" --output /tmp/edit-plan.json
• Clone a thread into another workspace: ./codex-history-manager clone-thread --id <thread-id> --to-cwd /abs/path --dry-run
• Move all threads in one workspace: ./codex-history-manager move-workspace --cwd /abs/src --to-cwd /abs/dst --dry-run
• Clone all threads in one workspace: ./codex-history-manager clone-workspace --cwd /abs/src --to-cwd /abs/dst --dry-run
• Move a thread to another workspace: ./codex-history-manager move-thread --id <thread-id> --to-cwd /abs/path --dry-run
• Rebind provider metadata: ./codex-history-manager change-provider --id <thread-id> --provider openai1 --dry-run
• Rebind provider metadata for one workspace: ./codex-history-manager change-provider-workspace --cwd /abs/path --provider openai1 --dry-run
• Rebind provider metadata for all local threads: ./codex-history-manager change-provider-all --provider openai1 --dry-run

Safety rules

• Never perform a write first. Use the default dry run or pass --dry-run.
• Only use --apply after reviewing the plan.
• Prefer cloning over moving unless the user explicitly wants to change ownership.
• Do not hand edit state_5.sqlite or rollout files if the CLI can do the job.
• If the user asks to modify message content, stop and confirm. You must first produce a dangerous edit plan, present the warning and change list in the conversation, and wait for explicit user approval before running apply-dangerous-edit.

Read these references only when needed:

• Command details: references/commands.md
• Write safety and backups: references/safety.md
• Storage model: references/storage.md