codex-maintenance

Inspect and repair local Codex session state using codex-tools.

12|2|Updated Jan 2, 2026

Search Tags:#codex #maintenance #config #sqlite #session #tools #transcripts

Ready to run

npx skills add https://github.com/osolmaz/tools --skill codex-maintenance

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: codex-maintenance
Source: https://github.com/osolmaz/tools/tree/main/agents/skills/codex-maintenance
Command: npx skills add https://github.com/osolmaz/tools --skill codex-maintenance

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Codex state maintenance is error-prone when editing live databases or session metadata. This skill provides a safe, guided approach to inspect and repair local Codex state using codex-tools, reducing risk and manual errors.

Core Features & Use Cases

Safe session state management: adjust cwd, title, and metadata using codex-tools instead of direct SQLite edits.
Transcript and rollout inspection: extract transcripts and review rollout JSONL files for debugging and migration.
Backups and validation: automatic backups and integrity checks before applying changes.

Quick Start

Run codex-maintenance to inspect a current Codex session and safely update its cwd and metadata as needed.

Frequently Asked Questions about codex-maintenance

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I safely update Codex session metadata without breaking the live database?▼

To safely update Codex session metadata, use codex-tools to adjust the cwd and title instead of making direct SQLite edits. This approach enforces safe practices by applying automatic backups and running integrity checks before any changes are committed.

What is the best way to inspect and export Codex transcripts for debugging?▼

The best way to inspect and export Codex transcripts is using a maintenance skill designed to extract session data and review rollout JSONL files. This allows you to safely inspect local state and debug issues without risking manual database corruption.

Can I manually edit the SQLite database to change my Codex session cwd?▼

You should not manually edit the SQLite database to change your Codex session cwd. Direct edits to live databases are error-prone; instead, apply changes through codex-tools with validation to ensure session state integrity is maintained.

How do I parse rollout JSONL files when migrating local Codex state?▼

To parse rollout JSONL files during migration, you can use codex maintenance tools to inspect and extract transcripts. This ensures you review the complete session history safely before applying any state modifications or metadata updates.

Why does directly modifying live Codex session state cause data corruption?▼

Directly modifying live Codex session state causes data corruption because manual SQLite edits bypass integrity checks. Using guided maintenance tools prevents this by automatically backing up data and validating changes before they are applied to the database.