Recipe Recover Missing History

Recipe: Recover Missing History

Use when: known Claude Code or Codex sessions are absent or incomplete in CCAM.

Procedure

1. Confirm filters, source, provider, date range, and project path.

2. Verify the provider's raw transcript files still exist and note their newest timestamps.

3. Export/backup CCAM before a large recovery import.

4. For the local default provider path:

   npx ccam import rescan

5. For another directory:

   npx ccam import path <absolute-directory>

6. For another machine, prefer Remote Data Sources or create a provider archive using the History Import guide.

7. Watch import progress and review imported, enriched, skipped, and failed counts.

8. Open one known session and verify metadata, events, transcript, agents, and token usage.

Why re-import is safe

The importer is designed to be idempotent. It can enrich or extend known sessions while avoiding duplicate insertion of already processed events. Still, use a backup before large or unusual archives.

Common causes

• hooks were installed after the session;
• dashboard was down during fail-open hook delivery;
• provider home or project path differs;
• file permissions prevent reading history;
• date/source filters hide imported rows;
• archive structure or provider selection is wrong;
• a remote source has not completed its provider sync.

Do not rename raw JSONL files or edit IDs to force import. Preserve originals and report a minimal failing archive with sensitive content removed.