Troubleshooting

No sources found

Run:

ctx sources --json

Confirm the provider keeps history on this machine and pass an explicit path if needed:

ctx import --path ~/.codex/sessions

In JSON output, native_import: true means ctx supports that provider format. importable: true means the current path has supported data available to import. A source can be native but still report missing, empty, or unknown on a specific machine.

Search misses recent work

Search defaults to --refresh auto, which performs a bounded best-effort refresh of discovered Codex session sources before querying. To force a catch-up, run:

ctx search "the missing phrase" --refresh strict
ctx import --provider codex
ctx search "the missing phrase"

Use --refresh off when you want to query only the existing index. Use ctx import --all or a provider-specific import when the missing work is from a non-Codex provider. Use ctx import --resume --json when you want output to mark the run as an idempotent rescan.

Strict refresh fails

--refresh strict fails when the pre-search refresh cannot run or import successfully. Run ctx sources --json to inspect source availability, then use ctx import --provider codex --progress plain for a foreground repair pass.

Store problems

Find the active root:

ctx status

The default is ~/.ctx. Check permissions and available disk space. Treat databases and logs as private local history when collecting diagnostics.