Skip to content
| Marketplace
Sign in
Visual Studio Code>Other>Codex HarborNew to Visual Studio Code? Get it now.
Codex Harbor

Codex Harbor

Snezhig

|
1 install
| (0) | Free
Remote-aware Codex session manager with local usage, search, groups, archive, and tab reload.
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

Codex Harbor

Codex Harbor is a workspace-aware session manager for the official OpenAI Codex VS Code extension. It adds a dedicated Codex Harbor icon to the left Activity Bar and keeps your Codex conversations organized without replacing the official Codex editor.

中文说明 · Report an issue

Highlights

  • Workspace-aware sessions — switch between the current workspace and all sessions on the current workspace host. The selected scope also applies to archived sessions.
  • Account & Usage — show the signed-in account, plan, available Codex allowance windows, and their reset times.
  • Practical session management — search, rename, group, archive, restore, and drag conversations between groups or into Archived.
  • No empty conversations — New session opens an official Codex draft. A real conversation is created only after the first message, then it is automatically associated with the workspace that opened it.
  • Native Codex experience — clicking a session opens the official Codex conversation editor; Codex Harbor does not implement or proxy the chat UI.
  • Localized sidebar — English and Simplified Chinese follow VS Code's display language.

Install

The first independent release is 0.1.0. Distribution starts with VSIX packages. Marketplace publishing is configured separately.

  1. Download codex-harbor-0.1.0.vsix and codex-harbor-local-bridge-0.1.0.vsix from this repository's GitHub Releases.
  2. In VS Code, run Extensions: Install from VSIX… for each package.
  3. Install and enable the official OpenAI Codex extension.
  4. Reload VS Code, then select Codex Harbor in the Activity Bar.

From a local terminal, the equivalent installation is:

code --install-extension ./codex-harbor-local-bridge-0.1.0.vsix
code --install-extension ./codex-harbor-0.1.0.vsix

For Remote SSH, WSL, or Dev Containers, install Codex Harbor on the workspace host and Codex Harbor Local Bridge locally. VS Code's Extensions view shows the installation host. Installing from a remote terminal alone will not install the bridge on your local computer.

Both packages are installed explicitly, so VSIX installation works before the bridge exists in Marketplace. For an update, install the newer VSIX packages.

Moving from Codex Ext

Disable the original Codex Ext and its Local Bridge before using Harbor: both can manage the same official Codex editor groups. Harbor has its own extension IDs (snezhig.codex-harbor and snezhig.codex-harbor-local-bridge), commands, views, settings, and local workspace state.

Existing Codex conversations remain available from Codex's session metadata. Custom groups and explicit workspace bindings stored by Codex Ext are not imported automatically. Recreate custom groups and copy any settings you need from codexWorkspaceSessions.* to codexHarbor.*.

Requirements

  • VS Code 1.96 or newer
  • OpenAI Codex (openai.chatgpt) for opening and managing native Codex conversations.

Remote SSH / Dev Containers

When using Remote SSH or Dev Containers, Codex Harbor runs with the workspace so the session list and session actions operate on that remote machine. Its separately installed Codex Harbor Local Bridge runs locally and reads the signed-in account and allowance from your local Codex installation. The two parts communicate through a VS Code command, so the remote session list and local account usage stay independent and correct.

The extension opens sessions through the official Codex conversation editor. Selecting an already-open chat reveals it in its existing editor group, even after you move it to another split. Other chats and drafts open in the editor group active when you click the sidebar action. The Harbor icon in each editor group's title bar creates a fresh chat tab in that group. No split is forced.

codexHarbor.chatGroupLocking controls file routing independently:

  • off: do not automatically lock groups.
  • chatOnly (default): lock groups containing only Codex chat tabs.
  • containsChat: lock any group containing a Codex chat, including mixed groups.

VS Code opens new files outside a locked group, using the most recently used unlocked group or creating one if none is available. Locking does not relocate existing file tabs. The policy manages matching chat groups on activation, group focus, tab opens/closes, and setting changes. Automatic locks are released when a managed group no longer matches the policy, including inactive groups that have lost their last chat, or when you select off. Groups the extension has not managed are left alone.

Lock/unlock commands target a resource unique to that group instead of relying on current focus. Empty groups or groups with only resources duplicated in other splits cannot be targeted safely; their lock update is deferred until a unique resource is available. VS Code's public tab API does not expose manual lock state, so groups adopted by this policy are managed as a whole; use off for manual control.

It reads Codex Desktop's local thread state to retain the same user-facing titles, workspace associations, and archive state as Codex. If that state is unavailable, it falls back to session_index.jsonl. Rename, archive, and restore use the app-server bundled with the official Codex extension; this keeps changes consistent with Codex without directly editing its local state.

The single, continuous sidebar has collapsible Account & Usage and Session Manager sections; their state is remembered per workspace. Its Account & Usage section shows the signed-in email, plan, one progress bar per available Codex allowance window, and its reset time. The Session Manager panel below has a tab-style Workspace / All sessions switch, a search field, and a new-session action. The session list follows directly below it and retains groups, archive, and restore. Account usage is not a conversation token estimate.

How it works

Codex Harbor reads session titles, workspace metadata, and archive state from the Codex data on the current workspace host. Rename, archive, and restore operations are performed by the official Codex app-server, so the changes remain consistent with Codex itself. Session grouping and workspace bindings are stored locally in VS Code for each workspace. No Codex Harbor cloud service receives your conversations.

Failed-tab recovery

The Reload Current Codex Tab arrow is also available in the title bar of a Codex editor, including drafts. It opens a fresh editor instance in the same group before closing the old tab, keeping the group alive even when it contains only that chat. A refused close rolls back the replacement and keeps the original. Reloading can discard unsent text. Reloading a /new draft reopens that draft route; use the existing session list to return to a conversation saved from a draft. Reloading does not fix an underlying official Codex UI startup failure.

Usage

  1. Install and enable the official OpenAI Codex extension.
  2. Open a folder or multi-root workspace.
  3. Click the Codex Harbor icon in VS Code's left Activity Bar.
  4. Use the Workspace / All sessions tabs to choose the scope. It applies to both active and archived sessions. Type in the search field to filter titles in the selected scope.
  5. Active sessions are organized into Ungrouped and user-defined groups. Drag a session to a group to move it; drag it to Archived to archive it. Drag an archived session back to an active group to restore and move it. Group data is stored per VS Code workspace.
  6. The Archived group follows the same scope filter. Clicking an archived row, or its restore action, restores that exact session to the active list. Rename, archive, and restore update the actual Codex conversation.
  7. Existing sessions are matched to their original workspace from Codex's local session metadata. Opening a session also binds it to the current workspace automatically, covering sessions whose metadata is unavailable.
  8. Use the search field to filter titles. Click a session to open it in a Codex editor tab.
  9. New session opens an official Codex draft. It does not create a local conversation until you send the first message. After that, Codex Harbor detects the real session and binds it to the workspace automatically.
  10. If an official Codex tab fails to initialize, right-click its tab and choose Reload Current Codex Tab. This recreates only that editor tab; unsent draft text in the tab is discarded.

The extension follows VS Code's display language. English is the default and Simplified Chinese is provided when VS Code uses zh-cn.

Bindings are held in VS Code workspaceState; each workspace keeps an independent sessionId → workspaceHash mapping. Workspace identifiers are SHA-256 hashes rather than raw paths.

Build and release

Use Node.js 22 or newer for the release toolchain.

npm ci
npm test
npm run package:all

This builds both VSIX packages using the root lockfile and toolchain. The runtime does not require npm packages. The icon sources are simple vector geometry in scripts/build-icon.cjs; npm run build:icon regenerates the SVG and PNG assets without external tools.

Set the same release version in both manifests and the root lockfile before tagging. Push a matching vX.Y.Z tag to run Build release packages. That workflow tests and packages both extensions, uploads workflow artifacts, and creates a draft GitHub Release with both VSIX files. Review its notes and publish the draft when ready. Running the workflow manually builds artifacts; it creates a draft release only when its selected ref is a version tag.

Marketplace publishing is a separate manual Publish to Marketplace workflow. Before using it, register the snezhig publisher (or update both manifests to your registered publisher), create the two extension entries, and configure Trusted Publishing for this repository's .github/workflows/publish.yml. Run the workflow with a matching release tag. It validates the version, runs tests, packages both extensions, and publishes the bridge before the main extension using OIDC. No Marketplace credentials are required for building or GitHub Releases.

See the upstream review for the changes selected from Codex Ext 0.6.17–0.6.19 and the reasons for deferring automatic recovery.

Privacy and data handling

  • Session titles, local workspace metadata, and archive state are read from the local Codex state on your computer; they are not sent to a Codex Harbor service.
  • Account and allowance data are requested from the official Codex extension's local app-server only.
  • Session grouping and workspace bindings are stored in VS Code workspaceState for the current workspace.

中文说明

Codex Harbor 是一个独立的 VS Code 扩展,用来管理本机的 OpenAI Codex 会话。

安装

本分支首先通过 GitHub Releases 中的 VSIX 文件分发,不代表已在 Marketplace 上架。 下载主扩展与 Local Bridge 两个 VSIX,在 VS Code 中分别执行 Extensions: Install from VSIX…,并安装官方 OpenAI Codex 扩展。

code --install-extension ./codex-harbor-local-bridge-0.1.0.vsix
code --install-extension ./codex-harbor-0.1.0.vsix

使用前请禁用原来的 Codex Ext 与其 Local Bridge。现有 Codex 会话仍可访问; 原扩展保存的自定义分组和工作区绑定不会自动导入。

Remote SSH / Dev Container

通过 Remote SSH 或 Dev Container 打开项目时,主扩展会运行在远端工作区一侧, 因此会话列表和会话管理针对远端机器。单独安装在本机的 Codex Harbor Local Bridge 运行在本机,读取本机 Codex 的登录账户和用量;两者通过 VS Code 命令通信, 因此远端会话与本机账户用量可以同时正确显示。

  • 按当前工作区或全部本地会话筛选;已归档会话也遵循该范围。
  • 显示官方 Codex 本地 app-server 返回的账户、套餐与可用额度。
  • 支持搜索、新建会话、新建分组、重命名、归档、恢复,以及拖拽到分组或 Archived。
  • 点击“新建会话”只会打开官方 Codex 草稿页;未发送消息便关闭时不会产生 空白会话。首次发送消息后,扩展会自动识别真实会话并绑定到当前工作区。
  • 官方 Codex 标签页加载失败时,可右键标签页并选择“重新加载当前 Codex 标签页”。该操作只重建当前标签页,但会丢弃该标签页中尚未发送的草稿内容。
  • 会话标题、工作区信息与归档状态只从本机 Codex 数据中读取;扩展不提供或 使用远端数据服务。

Acknowledgements

Codex Harbor is an independent fork of wzrzt/codex-ext, based on version 0.6.16 with selected later fixes. The original MIT license and copyright notices are preserved. Harbor adds editor-group handling, its own branding, and independent release packaging.

Earlier upstream design work was informed by ramusuco/codex-companion.

Codex is a trademark of OpenAI. This independent extension is not affiliated with or endorsed by OpenAI. Harbor uses its own bracket-and-dot icon.

Development guidance is available in CONTRIBUTING.md.

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft