README.en.md

codex-thread-path-fix

One-click fixer for Codex Desktop thread disappearance caused by path-key mismatch.

Typical symptoms:

• A workspace shows no threads in the left sidebar.
• Old threads can still be opened from history/context.
• Two equivalent paths (for example /Volumes/... vs /Users/...) are treated as different cwd keys.

This tool safely normalizes:

• threads.cwd in ~/.codex/state_5.sqlite
• workspace root keys in ~/.codex/.codex-global-state.json
• trust entries in ~/.codex/config.toml
• optional rollout metadata (session_meta.payload.cwd) in related session files

Requirements

• macOS / Linux
• bash
• sqlite3
• jq

Quick start

Preview only (no writes):

./scripts/fix-codex-thread-path.sh \
  --old-path "/Volumes/<disk>/anti coding/getbiji" \
  --new-path "/Users/<username>/anti coding/getbiji" \
  --dry-run

Apply changes (auto-stop Codex.app if needed):

./scripts/fix-codex-thread-path.sh \
  --old-path "/Volumes/<disk>/anti coding/getbiji" \
  --new-path "/Users/<username>/anti coding/getbiji" \
  --kill-app \
  -y

Options

• --old-path: old workspace path key
• --new-path: new canonical workspace path key
• --codex-home: Codex state directory (default ~/.codex)
• --include-rollouts: fix rollout metadata too (default on)
• --no-include-rollouts: skip rollout metadata
• --replace-global-text: replace old path in all strings in .codex-global-state.json
• --kill-app: auto-stop Codex.app processes
• --dry-run: preview only
• -y, --yes: no confirmation prompt

Why rollout fix matters

In many cases, fixing only sqlite/config/global-state is not enough.
Some builds also rely on rollout session_meta.cwd for workspace filtering.

That is why rollout fix is enabled by default.

Backups and rollback

Each apply run creates:

• ~/.codex/backups/<timestamp>-codex-path-fix
• If trust level cannot be inferred from old/new project blocks, the script uses safe default untrusted.

Backups include:

• state_5.sqlite
• .codex-global-state.json
• config.toml
• modified rollout files (if rollout fix is enabled)

Restore example:

BK="$HOME/.codex/backups/<your-backup-dir>"
cp "$BK/state_5.sqlite" "$HOME/.codex/state_5.sqlite"
cp "$BK/.codex-global-state.json" "$HOME/.codex/.codex-global-state.json"
cp "$BK/config.toml" "$HOME/.codex/config.toml"

Tests

bash -n ./scripts/fix-codex-thread-path.sh
bash -n ./tests/smoke.sh
./tests/smoke.sh

Open-source docs

• Contributing guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Changelog: CHANGELOG.md
• Release checklist: docs/RELEASE_CHECKLIST.md
• Issue/PR templates: .github/ISSUE_TEMPLATE/*, .github/pull_request_template.md

Full guide

• Chinese deep-dive: docs/教程_双路径线程消失修复.md