Codex Harbor
Highlights
InstallThe first independent release is 0.1.0. Distribution starts with VSIX packages. Marketplace publishing is configured separately.
From a local terminal, the equivalent installation is:
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 ExtDisable 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 ( 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 Requirements
Remote SSH / Dev ContainersWhen 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.
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 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 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 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 worksCodex 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 recoveryThe 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 Usage
The extension follows VS Code's display language. English is the default and
Simplified Chinese is provided when VS Code uses Bindings are held in VS Code Build and releaseUse Node.js 22 or newer for the release toolchain.
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 Set the same release version in both manifests and the root lockfile before
tagging. Push a matching Marketplace publishing is a separate manual Publish to Marketplace workflow.
Before using it, register the 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
中文说明Codex Harbor 是一个独立的 VS Code 扩展,用来管理本机的 OpenAI Codex 会话。 安装本分支首先通过 GitHub Releases 中的 VSIX 文件分发,不代表已在 Marketplace 上架。 下载主扩展与 Local Bridge 两个 VSIX,在 VS Code 中分别执行 Extensions: Install from VSIX…,并安装官方 OpenAI Codex 扩展。
使用前请禁用原来的 Codex Ext 与其 Local Bridge。现有 Codex 会话仍可访问; 原扩展保存的自定义分组和工作区绑定不会自动导入。 Remote SSH / Dev Container通过 Remote SSH 或 Dev Container 打开项目时,主扩展会运行在远端工作区一侧, 因此会话列表和会话管理针对远端机器。单独安装在本机的 Codex Harbor Local Bridge 运行在本机,读取本机 Codex 的登录账户和用量;两者通过 VS Code 命令通信, 因此远端会话与本机账户用量可以同时正确显示。
AcknowledgementsCodex 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. |