# Codex History Reconcile

> Detect and repair missing Codex history after switching API keys or auth providers in VS Code. Use when old Codex threads still exist in `.codex/state_5.sqlite` or `.codex/sessions` but no longer appear in the sidebar/history, especially after changing between API key auth, ChatGPT account auth, or Copilot auth. Verifies required tools, checks the current visible thread provider, backs up local state, and remaps top-level VS Code thread providers to the currently visible auth provider.

- Skill: `e-zegna/codex-history-reconcile` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add e-zegna/codex-history-reconcile`
- Raw SKILL.md: https://api.skillmd.com/api/skills/e-zegna/codex-history-reconcile/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: E-ZEGNA (https://skillmd.com/u/e-zegna)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/e-zegna/codex-history-reconcile

---


# Codex History Reconcile

## Overview

Detect when Codex history exists locally but is hidden by provider filtering, then safely remap top-level VS Code threads to the provider visible under the current login mode.

## Workflow

1. Run `node scripts/codex-history-reconcile.js check`.
2. Confirm the environment is healthy and inspect:
   - current auth mode
   - current visible provider
   - visible thread count from `codex app-server`
   - top-level `source='vscode'` thread counts by provider from `.codex/state_5.sqlite`
3. If the visible thread count is unexpectedly low and the target provider is clear, run a dry run:

```powershell
node scripts/codex-history-reconcile.js reconcile --dry-run
```

4. If the dry run matches expectations, run the real migration:

```powershell
node scripts/codex-history-reconcile.js reconcile
```

5. Reload or restart VS Code so the history panel refreshes from the updated thread data.
6. Re-run `check` to verify the visible thread count now matches the expected top-level history count.

## Safety Rules

- Back up `state_5.sqlite` and affected session files before writing.
- Modify only top-level `source='vscode'` threads by default.
- Leave sub-agent threads alone unless the user explicitly asks to retag them.
- Do not edit thread content or turn payloads; only update provider metadata.
- If target provider auto-detection is ambiguous, stop and require `--target-provider`.

## Environment Checks

Use the built-in check command before any write:

```powershell
node scripts/codex-history-reconcile.js check
```

The script validates:

- Node.js version and `node:sqlite` availability
- `.codex/state_5.sqlite` and `.codex/sessions` existence
- VS Code `state.vscdb` existence
- Codex CLI or extension-bundled `codex` executable discovery
- current login status from `codex login status`
- current visible thread list from `codex app-server`

## Auto-Detection Rules

The reconcile script chooses the target provider in this order:

1. Use the single provider returned by the current visible `thread/list` response.
2. If login status says API key auth, use `custom`.
3. If login status suggests ChatGPT or OpenAI auth, use `openai`.
4. If login status suggests Copilot auth, prefer `fluxcode`.
5. If still ambiguous, require `--target-provider`.

## Commands

Inspect only:

```powershell
node scripts/codex-history-reconcile.js check
```

Preview the change set:

```powershell
node scripts/codex-history-reconcile.js reconcile --dry-run
```

Force a specific provider:

```powershell
node scripts/codex-history-reconcile.js reconcile --target-provider custom
```

Include archived top-level threads:

```powershell
node scripts/codex-history-reconcile.js reconcile --include-archived
```

## Resources

### scripts/

- `scripts/codex-history-reconcile.js`: Check environment, inspect visible history, back up local state, and retag top-level thread providers.