Codex Project Chat Resumer

codex-project-chat-resumer is a separate VS Code extension that opens the official OpenAI Codex sidebar and restores the newest non-archived Codex VS Code conversation whose working directory exactly matches the current project.

It does not modify the official extension, its bundle, or Codex conversation files.

It is an independent community companion and is not affiliated with or endorsed by OpenAI.

Install

Version 0.4.1 is a universal extension for Windows, macOS, and Linux. It supports x64 and ARM64 hosts whenever the official Codex extension supports that host.

1. Open the VS Code Extensions view.
2. Search for Codex Project Chat Resumer.
3. Select Install.
4. Sign into the official OpenAI Codex extension if needed.
5. Reopen a project folder.

The official Codex extension is declared as a dependency, so VS Code installs it automatically when necessary. Marketplace updates are automatic.

Compatibility status

Version 0.4.1 retains the universal package and adds per-window focus leases for safe multi-window restoration, bounded official-extension activation, delayed command-registration handling, paginated history discovery, remote-workspace host placement, Unicode/UNC path coverage, and an optional dedicated conversation tree. Current official bundles were inspected for the exact layouts used by Windows x64 (windows-x86_64/codex.exe), macOS Apple Silicon (macos-aarch64/codex), and macOS Intel (macos-x86_64/codex). Linux x64 was exercised end to end locally. Windows and macOS discovery paths are covered by automated tests, but should still be confirmed with Codex: Check Project Chat Resumer Setup on the first machine of each type.

Native Windows, macOS, and Linux workspaces are supported. The extension prefers the workspace extension host so Remote SSH, WSL windows, and dev containers can use the Codex installation and filesystem beside the project. Native Windows windows configured to redirect Codex into WSL are rejected with a clear instruction to reopen the project in a VS Code WSL window; silently mixing Windows and WSL histories could select the wrong project.

Conversation discovery uses the documented Codex App Server thread/list method. Displaying a selected thread uses an undocumented but callable URI exposed by the installed official extension:

vscode://openai.chatgpt/local/<threadId>

The scheme follows the running editor (vscode for stable VS Code, vscode-insiders for Insiders). The official extension's URI handler opens the sidebar, forwards the /local/<threadId> route to its webview, and queues the route until that webview is ready. The public command list does not currently include an openThread command, so this URI is the narrowest safe bridge. It may change in a future official-extension release; run Codex: Show Project Chat Resumer Diagnostics after an update if restoration stops working.

Official references:

• Codex IDE extension commands
• Codex App Server

Behavior

On onStartupFinished, after the configured delay, the extension:

1. Waits until this VS Code window is focused, so a background project window cannot route a chat into another window.
2. Resolves the current workspace folder path and its real path.
3. Starts Codex App Server over local stdio.
4. Calls thread/list with sourceKinds: ["vscode"], archived: false, sortKey: "recency_at", sortDirection: "desc", limit: 1, and the exact safe workspace path spellings.
5. Activates the official Codex extension, with a five-second timeout, then waits up to five seconds for its sidebar command.
6. Calls the documented chatgpt.openSidebar command.
7. Revalidates that the initiating window is still focused, then opens the selected thread by its authoritative thread ID through the official extension URI above. If focus changed during discovery, the route is suppressed and automatic restoration retries when that project window next receives focus.

Conversation names are logged only as readable metadata. Renaming a conversation, or giving multiple conversations the same name, does not affect selection.

If there is no matching conversation, Codex opens normally. If discovery fails, VS Code remains usable, one concise warning is shown, and details are written to the Codex Project Chat Resumer output channel. Transient App Server startup failures are retried once.

For a multi-root workspace, the active editor's folder is used. If no editor identifies a folder during automatic startup, Codex opens normally and automatic thread selection is skipped. The manual restore command offers a folder picker.

What “latest” means

Automatic restoration uses App Server's supported recency_at ordering. OpenAI does not currently expose a documented event for “the user silently selected this item in the official sidebar.” Resuming an already-current thread does not change its updatedAt, and a local verification found that reopening the already-current URI changed neither updatedAt nor recencyAt. The extension therefore does not scrape private Codex storage or claim it can observe an event that is not exposed. Conversations opened from the companion tree always use the exact selected thread ID.

Optional conversation collections

Select the Codex Chats icon in the Activity Bar to open the dedicated Project Conversations tree. Opening the tree pages through non-archived VS Code conversations for each workspace folder; it does not read turn bodies.

Every conversation starts under Unfiled. Collections are entirely manual and optional:

1. Select the new-folder button in the tree title, or right-click a project and choose Create Conversation Collection.
2. Right-click a conversation and choose Move Conversation to Collection.
3. Select a conversation to open it in the official Codex sidebar.

You can rename or delete a collection, set a local alias, clear an alias, and copy the authoritative thread ID. Deleting a collection only removes the companion's local organization metadata; its conversations return to Unfiled. It never deletes, archives, renames, moves, or edits Codex history.

Collection assignments and aliases are stored in VS Code's workspace-scoped extension storage, not in the project repository. No project files or .vscode settings are created. The tree is loaded only when VS Code requests it and can be hidden or moved like any other VS Code view.

Build from source

From this repository:

npm ci
npm run check
npm run package:marketplace
code --install-extension ./codex-project-chat-resumer-0.4.1.vsix --force

The Marketplace build intentionally omits --target, producing one universal VSIX for Windows, macOS, and Linux. The package name follows the version in package.json, and packaging updates SHA256SUMS.txt. Maintainers can use npm run publish:marketplace after authenticating the matching publisher; this command cleans, rebuilds, tests, and packages the current source before publishing. The validated VSIX can also be uploaded through the publisher portal.

Reload VS Code after installation.

Commands

• Codex: Restore This Project's Latest Codex Conversation — restore immediately, ignoring the startup delay.
• Codex: Check Project Chat Resumer Setup — verify the official extension, runtime command, platform-native CLI, App Server, normalized folder path, and local history query.
• Codex: Show Project Chat Resumer Output — open concise diagnostic logs.
• Codex: Show Project Chat Resumer Diagnostics — report the installed official extension and all runtime-registered chatgpt.*/codex.* commands.
• Codex: Refresh Project Conversations — reload the optional tree from App Server.
• Codex: Create Conversation Collection — manually add a local collection for the selected project.

Additional collection, alias, thread-ID, and open actions appear in the tree item's context menu.

Settings

{
  "codexProjectChatResumer.enabled": true,
  "codexProjectChatResumer.startupDelayMs": 750,
  "codexProjectChatResumer.codexCliPath": null,
  "codexProjectChatResumer.appServerTimeoutMs": 10000,
  "codexProjectChatResumer.notifyOnError": true
}

When codexCliPath is unset, the companion prefers the Windows, macOS, or Linux CLI bundled with the installed openai.chatgpt extension, then falls back to codex on PATH. The configured path must be an absolute path to an executable file; on Windows this is normally a codex.exe path.

Troubleshooting

• Official extension missing: install and enable openai.chatgpt. It is declared as a Marketplace dependency and is also checked defensively at runtime.
• Codex CLI or App Server unavailable: run the diagnostics command and inspect the output channel. Set codexProjectChatResumer.codexCliPath only when automatic discovery cannot find a working CLI.
• Sidebar opens but the thread does not change: the official extension may have changed its undocumented URI route. The output reports whether VS Code accepted the URI. No DOM or mouse automation is used as a fallback.
• No thread is restored: only non-archived conversations with source vscode and an exact normalized workspace cwd are eligible. Archived, CLI-only, app-server, and other-project conversations are excluded.
• Several project windows are open: background windows keep their automatic restoration pending. Each window restores only when focused, and a result discovered before a focus change is never sent through the application-level thread URI.
• Symlinked folder: both the folder spelling opened in VS Code and its real path are sent as exact App Server filters, and the returned thread path is canonicalized again before navigation. Other projects are rejected.
• Remote SSH, WSL, or dev container: install/enable both the companion and official Codex extension in the workspace extension host. Run Developer: Show Running Extensions to confirm placement.
• Native Windows with “Run Codex in WSL”: reopen the folder with WSL: Open Folder in WSL. The companion intentionally refuses to mix native Windows paths with WSL history.
• Tree collection disappeared: collection metadata is workspace-scoped and local to that VS Code host. Codex history is unaffected and all live conversations remain discoverable after a refresh.

Tests

npm test covers concurrent project-window isolation, background startup deferral, focus changes during discovery, stale-result suppression, Windows/macOS/Linux bundled-CLI discovery, x64 and ARM64 naming, delayed command registration, App Server JSONL initialization and pagination, archived/source/cwd filters, no-history behavior, ID-based selection despite duplicate names, missing-process errors, exact project filters, Unicode and UNC paths, symlink canonicalization, remote-host placement, corrupted organization state, manual collection assignment, aliases, and non-destructive collection deletion. Regression tests also cover stalled activation and command discovery, broken App Server pipes, malformed JSON messages, and buffered output during process shutdown. The live installed Linux CLI was also probed with the same thread/list request used by the extension.

The URI itself belongs to the official extension and cannot be meaningfully unit-tested without an Extension Development Host. Use the diagnostics command to inspect the commands registered in the running VS Code instance.

Privacy

This companion collects no telemetry and has no analytics service. Automatic restoration asks the locally installed Codex App Server for one summary filtered to the current workspace. The optional tree pages through matching summaries and immediately narrows every response to IDs, names/previews, working directories, and timestamps; turn bodies and unrecognized response fields are discarded. Local collections contain only collection names, thread-ID assignments, and optional aliases. The selected thread ID is passed to the official Codex sidebar.

Artwork

The extension icon is a restored close crop of an unidentified photographer's circa-1865 portrait of Charles-Valentin Alkan, sourced from the Bibliothèque nationale de France via Wikimedia Commons. The source photograph is marked as public domain.