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
This release targets Ubuntu/Linux x64 only.
- Open the VS Code Extensions view.
- Search for Codex Project Chat Resumer.
- Select Install.
- Sign into the official OpenAI Codex extension if needed.
- 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.2.0 was verified on Ubuntu x64 across an automatic official-extension update: openai.chatgpt versions 26.727.40816 and 26.803.41515, with bundled Codex CLI versions 0.146.0-alpha.9.2 and 0.147.0-alpha.6.5. The official extension's versioned installation directory changed during testing; runtime discovery continued to use the current extension path.
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 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:
Behavior
On onStartupFinished, after the configured delay, the extension:
- Resolves the current single-folder workspace path and its real path.
- Starts Codex App Server over local stdio.
- Calls
thread/list with sourceKinds: ["vscode"], archived: false, sortKey: "recency_at", sortDirection: "desc", limit: 1, and the exact safe workspace path spellings.
- Calls the documented
chatgpt.openSidebar command.
- Opens the selected thread by its authoritative thread ID through the official extension URI above.
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.
Build from source
From this repository:
npm install
npm run check
npm run package:marketplace
code --install-extension ./codex-project-chat-resumer-0.2.0-linux-x64.vsix --force
The Marketplace build is explicitly targeted with vsce package --target linux-x64. Maintainers can publish the validated package with npm run publish:marketplace after authenticating the matching publisher.
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, Ubuntu 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.
Settings
{
"codexProjectChatResumer.enabled": true,
"codexProjectChatResumer.startupDelayMs": 750,
"codexProjectChatResumer.codexCliPath": null,
"codexProjectChatResumer.appServerTimeoutMs": 10000,
"codexProjectChatResumer.notifyOnError": true
}
When codexCliPath is unset, the companion prefers the CLI bundled with the installed openai.chatgpt extension, then falls back to codex on PATH. The configured path must be an executable file.
Troubleshooting
- Official extension missing: install and enable
openai.chatgpt. The companion intentionally has no hard extension dependency so it can activate and report this condition.
- 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.
- 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.
Tests
npm test covers the App Server JSONL handshake and request, no-history behavior, ID-based selection despite duplicate names, missing-process errors, exact project filters, and symlink canonicalization. The live installed 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, has no analytics service, and does not read conversation contents itself. It asks the locally installed Codex App Server for one thread summary filtered to the current workspace and passes that thread ID 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.
