| name | codex-maintenance |
| description | Use when maintaining local Codex state, including changing or repairing session cwd/title/metadata, inspecting rollout JSONL files, extracting transcripts, transferring Codex sessions between machines, editing trusted project config, or using the tools repo codex-tools CLI. Prefer this skill for work involving ~/.codex/state_5.sqlite, ~/.codex/sessions, ~/.codex/config.toml, local Codex session repair, and Codex session transfer. |
Codex Maintenance
Use this skill for local Codex state maintenance. The source tool is
~/repos/tools/codex-tools.
Core Rules
- Prefer
codex-tools over manual edits for session state changes.
- Do not raw-edit
~/.codex/state_5.sqlite.
- Do not rewrite user-visible transcript messages when changing cwd; update only
session metadata.
- Treat
~/.codex/sessions/**/*.jsonl, ~/.codex/state_5.sqlite, and
~/.codex/config.toml as live user state. Back up before manual changes.
- Remember that the currently running Codex process may keep its old cwd until
the thread reloads or resumes. Persisted state is what these tools change.
Change Session Cwd
Identify the target session by full ID, unique prefix, or rollout JSONL path.
Dry-run first unless the user explicitly asked to apply immediately.
When the target session is already known, the first command should be the
codex-tools set-cwd ... --dry-run command. Do not start with pwd; pwd
only reports the shell's current directory and does not validate or repair
persisted Codex session state.
cd ~/repos/tools/codex-tools
cargo run --bin codex-tools -- set-cwd <session-id-or-prefix-or-rollout-jsonl> <new-cwd> --dry-run
cargo run --bin codex-tools -- set-cwd <session-id-or-prefix-or-rollout-jsonl> <new-cwd>
If the user says "this session" but the session ID is not available in context,
first identify the session from Codex state, then run the dry-run:
sqlite3 ~/.codex/state_5.sqlite "SELECT id, cwd, title FROM threads ORDER BY updated_at DESC LIMIT 10;"
By default, set-cwd updates:
- the thread row in
~/.codex/state_5.sqlite;
- rollout
session_meta and turn_context cwd metadata;
- the trusted project entry in
~/.codex/config.toml.
Use --no-trust-project only when the user does not want the new cwd added as a
trusted Codex project.
The tool creates backups and verifies PRAGMA integrity_check around SQLite
updates. If it fails, stop and inspect before retrying.
Extract Session Transcripts
Use transcript extraction for readable summaries or migration/debugging.
cd ~/repos/tools/codex-tools
cargo run --bin codex-tools -- extract <rollout.jsonl>
cargo run --bin codex-tools -- extract <rollout.jsonl> --jsonl
Use plain output for reading and --jsonl when another tool needs structured
messages.
Transfer Sessions Between Machines
When the user asks to transfer, copy, migrate, move, export, import, or resume a
Codex session on another machine, use cct from Onur's fork:
https://github.com/osolmaz/codex-claude-transfer.
The local source checkout is usually:
cd ~/repos/codex-claude-transfer
If it is missing, clone the fork into ~/repos:
git clone https://github.com/osolmaz/codex-claude-transfer.git ~/repos/codex-claude-transfer
cd ~/repos/codex-claude-transfer
If the cct binary is not present, build it from the checkout:
go build -o cct ./cmd/cct
Export the target session to a .codexbundle:
./cct list --tool codex
./cct export --tool codex --session <session-id-or-prefix> --output <name>.codexbundle
On the destination machine, import the bundle instead of editing SQLite:
./cct inspect <name>.codexbundle
./cct import <name>.codexbundle
Use --dry-run before import when the destination state is not known. Use
--map-cwd-here or --map-cwd OLD=NEW when the project lives at a different
path on the destination machine. After import, restart or resume Codex so it
re-scans the rollout files and updates its own index.
Important constraints:
- Do not copy or raw-edit
~/.codex/state_5.sqlite to transfer sessions.
- Do not manually place rollout files unless
cct is unavailable and the user
explicitly accepts a manual fallback.
- Treat
.codexbundle files as sensitive; they can contain prompts, code,
terminal output, image payloads, and secrets.
- Prefer redaction/encryption when transferring bundles through any untrusted
channel.
Verification
After changing session state, verify the persisted state:
sqlite3 ~/.codex/state_5.sqlite "PRAGMA integrity_check;"
sqlite3 ~/.codex/state_5.sqlite "SELECT id, cwd FROM threads WHERE id = '<session-id>';"
rg '"cwd":|cwd' ~/.codex/sessions -g '*.jsonl'
rg '<new-cwd>' ~/.codex/config.toml
If the session was selected by prefix, first resolve the full session ID from
the command output and use that exact ID for targeted checks.
Manual SQLite Inspection
Only inspect SQLite manually when codex-tools does not cover the task.
sqlite3 ~/.codex/state_5.sqlite "PRAGMA integrity_check;"
sqlite3 ~/.codex/state_5.sqlite ".schema threads"
sqlite3 ~/.codex/state_5.sqlite "SELECT id, cwd, title FROM threads ORDER BY updated_at DESC LIMIT 20;"
Before any manual write, create a backup with VACUUM INTO or a copied snapshot
while no Codex process is actively writing to the database. Verify
PRAGMA integrity_check again after the write.
Source Changes
When changing the maintenance tooling itself:
cd ~/repos/tools/codex-tools
cargo test
cargo clippy -- -D warnings
Keep edits in ~/repos/tools. To refresh installed agent resources, switch to
the OnurPi checkout and run:
npm run agents:sync -- codex-maintenance
