Open Codex CLI

A community-maintained Codex CLI fork that stays close to upstream while making room for openly developed CLI improvements.

Install with npm install -g @leonw24/open-codex, then run open-codex.

GitHub README does not allow JavaScript-based language toggles, so this page uses collapsible language sections as the practical equivalent.

---

English

Motivation

Codex CLI is open source, but upstream code contributions are currently invitation-only. The upstream repository states this clearly in docs/contributing.md: external pull requests that have not been explicitly invited will be closed without review.

That policy is understandable from the perspective of the upstream maintainers, but it also leaves a gap for developers who want to iterate in public, ship focused CLI improvements, and maintain a fork that can accept normal community collaboration. This repository exists to fill that gap.

The goal of Open Codex CLI is not to diverge for the sake of divergence. The goal is to keep a small, intentional delta on top of upstream Codex CLI, make that delta easy to understand, and keep the fork mergeable as upstream evolves.

Current Goals

• solve real Codex CLI usage problems I run into, whether they are bugs or features worth borrowing from Claude Code
• keep improving the Codex CLI experience under zellij (Fuck Off Tmux!)

Current Delta and Roadmap vs. Latest Upstream Codex CLI

This fork is currently based on the latest upstream openai/codex and adds a small set of focused CLI improvements from recent fork-specific commits:

1. General user-query highlighting in the TUI

From commit c652bb8db1:

• adds a shared user_message_style() for user-authored query surfaces instead of a Zellij-only transcript contrast path
• applies the same terminal-background-aware user-query highlight to the chat composer panel and to committed UserHistoryCell messages in chat history
• wraps historical user queries with top/bottom divider lines and keeps the User › prefix visually distinct, so user prompts are easier to scan in long transcripts
• keeps the styling adaptive across light and dark terminal backgrounds rather than hardcoding a single foreground/border color

This is a general TUI readability improvement: the active user query in the chat box and previous user queries in history now share one consistent highlight language, making user-authored turns easier to identify without tying the behavior to zellij.

2. Stale turn output protection in the TUI

From commit 67b06fd086:

• adds turn-aware filtering at the live TUI notification/render boundary
• drops stale assistant message, plan, and reasoning deltas when they belong to an older turn
• drops stale completed assistant/plan/reasoning items from live thread-item notifications
• ignores stale turn-completion notifications so an old completion cannot end the current turn
• keeps replay explicitly separate, so resumed thread snapshots can still render historical content
• adds regression coverage for stale deltas, stale completed items, and stale completions

This is a correctness-focused patch: the UI should not render output from the wrong turn, even when retry, replay, or stream timing gets messy.

3. Active memory staging on upstream memories

The earlier fork-only memory subsystem has been removed so the fork stays aligned with upstream's memory architecture. The current memory change is intentionally narrow:

• Upstream memory remains the source of truth — Codex still uses upstream memory_summary.md, MEMORY.md, topic files, skills, and extensions/ad_hoc consolidation. The memories feature keeps the upstream experimental gate and is disabled by default.

• Active staging tool — When the memory feature is enabled, Codex exposes memory_stage_update. It writes a small ad-hoc note under ~/.codex/memories/extensions/ad_hoc/notes/ for upstream consolidation and stages the same content into the current session.

• Session Memory Overlay — Staged entries are injected as a bounded developer-context overlay for the current session, so newly saved information can affect the next turn without waiting for a new session or background consolidation. The overlay is emitted only when its revision changes.

• Explicit staging feedback — memory_stage_update now returns the staged content, optional reason, overlay revision, and ad-hoc note path, so the model can tell the user exactly what was staged and where the durable consolidation input was written.

• Global overlay diagnostics — /memory-overlay shows all loaded session overlay entries plus global ad-hoc staged notes, and reports exact matches already present in durable memory files. It is a diagnostic view, not a semantic-proof system: unmatched entries may still be pending consolidation or may have been paraphrased by the consolidation agent.

• Overlay status metrics — Each /memory-overlay row is grouped by source (Session overlays or Ad-hoc staged notes) and carries a status metric: matched means the staged content has an exact text match in a durable memory file, while pending means no exact durable match was found. Matched rows include the durable file paths, such as MEMORY.md or topics/*.md. This makes durable visibility auditable today, while leaving explicit Phase 2 provenance (selected/consumed but paraphrased) as a future metric rather than pretending exact-match checks can prove semantic consolidation.

• Durable memory browser — /memory opens the current durable memory content grouped by Summary, Overall index, and Topics, so users can inspect what the next session will actually read from the upstream memory files instead of inferring durable state from overlay diagnostics alone.

• Removed conflicting fork behavior — The old direct durable write tools, notepad file, topic frontmatter priority system, merge-write path, and custom AGENTS.md hierarchy are no longer part of the memory implementation.

This addresses the active-update gap while keeping durable memory storage and consolidation compatible with upstream.

4. Open Codex-aware update detection and upgrade prompts

From commit e1e88af89d:

• switches npm/bun update detection from upstream Codex metadata to the fork package @leonw24/open-codex
• updates upgrade commands and release notes links so prompts point to Open Codex instead of @openai/codex
• keeps the runtime check aligned with the actual package users install from npm

This is a fork-correctness patch: update notifications should describe the Open Codex release a user can actually install, not the upstream Codex CLI release stream.

5. Session export inside the TUI

From recent fork-specific changes:

• adds /export <path> for the current session transcript
• supports user-chosen filenames like /export talk.md or /export talk.txt
• writes a markdown transcript suitable for debugging, archival, and sharing

This brings a Claude Code-style export flow into the TUI without requiring external scripts or manual transcript scraping.

6. Reasoning effort controls and per-turn status visibility

From recent fork-specific changes:

• adds /effort for changing the active reasoning effort directly from the TUI
• supports one-turn high-effort markers in the user query: standalone ulw, ultra, or xhigh submit that turn with xhigh reasoning
• keeps marker-based xhigh current-turn-only, so it does not mutate the session's default effort
• shows the submitted per-turn effort in the model-with-reasoning status-line item while that foreground turn is pending or running
• restores the status line to the session/default effort when the turn completes, fails, or is interrupted

This closes the UX gap between "the request was submitted with xhigh" and "the footer still looks like high": the status line now describes the active foreground turn without making a temporary marker look like a persistent configuration change.

7. Lightweight /btw side questions

From recent fork-specific changes:

• ask quick side questions with /btw <question> without taking over the main chat
• keep short follow-ups inside the BTW bottom pane instead of turning them into the primary task
• use the same model, effort, permission, and tool behavior users expect from the main session

This is intended for "by the way" questions that are useful during work but should not become the primary task thread.

8. Parallel-first subagent planning policy

Implemented through the user-scope ~/.codex/AGENTS.md instruction layer, with an extracted repo example in docs/parallel-first-agent-execution.md:

• overrides Codex's default conservative stance against automatic agent spawning with an explicit, more aggressive subagent policy for complex work
• classifies non-trivial work by independent investigation, review, test, docs, and validation axes before editing
• prefers read-only subagents for evidence gathering, with one final implementation lane unless edit boundaries are clearly disjoint
• keeps the stable profile set small (default, explorer, worker) while describing each subtask with clear task context and ownership
• encourages subagents across exploration, review, verification, and release checks when those lanes are genuinely independent

This is an instruction-policy feature rather than a hardcoded scheduler: it enables a more aggressive subagent mechanism while keeping shared-file edits coordinated.

9. Nonblocking background execution

From recent fork-specific TUI changes:

The feature is centered on two background lanes:

• Terminal commands — long-running terminal sessions continue in the background instead of keeping the main turn blocked by foreground waiting or polling. Empty command/exec/write interactions keep the terminal backgrounded, so normal chat input can be submitted while the shell process continues.
• Subagents — long-running agent work is tracked as background activity after spawn/wait tool calls complete, including agent nickname, role, status, and progress lines when available.

The shared interaction model is:

• Ctrl+B sends the current terminal activity to the background while keeping streamed output available.
• Down opens a live task panel with separate Tasks, Subagents, and Terminals sections.
• Enter opens details, x stops the selected stoppable background item, and Esc/Left closes the panel.
• the status line keeps foreground Working state separate from background subagent/terminal counts.
• terminal details show runtime and recent output; subagent details show role, task, status, runtime, progress, and task-boundary context.
• /agent shows available agent profiles, while /subagents keeps the subagent thread picker/switching workflow.
• completed subagent work wakes the parent turn through a core completion event, so results can be integrated without manually calling wait_agent or closing the agent.
• completed subagents are reclaimed from spawn quota when they reach a final state, and the spawn path performs opportunistic cleanup before reporting that no quota is available. Interrupted subagents remain visible as active quota holders because they may still be resumed; /subagents is therefore the active/resumable subagent view, not a stale-handle inventory.
• completed background command output is preserved in history without pulling the task back into the foreground.

This is the essential interaction change behind the Claude Code-style behavior: background work stays visible and controllable, but it no longer blocks normal chat flow.

10. Status line token throughput visibility (Beta)

From commit 85e937b855:

• adds a configurable status-line item for session-average input/output token throughput
• renders as in <rate> / out <rate> tok/s when enough token-usage and turn-duration data has been observed
• falls back to in -- / out -- tok/s before a usable sample exists
• computes a coarse session average from completed turn usage and duration, including interval merging for overlapping active windows

This is intentionally marked Beta: the current value is useful as a rough responsiveness signal, but it is not yet an exact real-time throughput metric.

11. Workspace git status in the status line

The status line can now surface the current workspace diff through the configurable workspace-changes item:

• renders tracked changes as +<added>/-<deleted> using Git numstat data from the active workspace
• appends ?<count> when untracked files are present, so a dirty workspace is still visible even before files are staged or modified in tracked paths
• hides itself for clean workspaces, keeping the status line compact when there is nothing to review

This is intended as a lightweight situational-awareness signal: it answers "did this session leave local changes behind?" without opening a separate shell or /status view.

Near-term roadmap

The near-term roadmap is intentionally focused on a few CLI-facing improvements:

1. Status line throughput visibility ✅ Beta

Initial support is implemented as a beta status-line item. The remaining work is accuracy: the current estimator is session-average and timing-derived, so it should not be treated as precise real-time token throughput yet.

2. Session export ✅ Completed

Implemented as a Claude Code-style /export flow for the current session, with user-defined filenames like /export talk.txt or /export talk.md. This now covers the debugging, sharing, and archival use case directly inside the TUI.

3. Better memory mechanics

Active memory staging is implemented on top of upstream memories (see Current Delta section 3 above). Broader durable-memory behavior should continue to follow upstream so fork changes stay additive. The main remaining observability gap is a native Phase 2 provenance metric that can distinguish not selected yet, selected/consumed but paraphrased, and exact durable match.

4. Better Zellij ergonomics

Continue improving the Codex CLI experience under zellij, especially around rendering, layout, contrast, and other interaction details that behave differently from plain terminal sessions or tmux.

Next focus areas

• Better task management experience

Positioning vs. Wrapper Projects

Open Codex CLI is intentionally a native Codex fork, not a wrapper layer around the official CLI. Projects such as everything-claude-code and oh-my-codex are valuable because they can iterate quickly in TypeScript or configuration space: skills, prompts, hooks, setup flows, agent teams, and higher-level workflow policies can move faster outside the Rust runtime.

This fork targets the complementary layer: source-level CLI behavior that has to be correct inside Codex itself. That includes TUI rendering contracts, turn routing, foreground/background task state, status-line truth, memory-session integration, app-server protocol surfaces, update detection, and npm package identity. Wrapper projects can orchestrate those capabilities, but they should not have to emulate them with prompts or hooks.

Dimension	Open Codex CLI	Wrapper/workflow projects
Primary layer	Native Codex runtime and distribution	External orchestration around Codex or multiple coding agents
Typical implementation	Rust source changes in codex-rs, launcher/package changes in codex-cli, protocol/schema changes	TypeScript, shell scripts, config files, prompts, skills, hooks, MCP setup
Best for	TUI correctness, turn/session contracts, background task state, status-line truth, memory-session integration, app-server protocol, fork-aware updates	Fast workflow iteration, project setup, agent teams, prompt routing, skills, hooks, policy packs, cross-tool conventions
Iteration speed	Slower, because changes need Rust builds, tests, and upstream-merge discipline	Faster, because behavior can change through TS/config/prompt layers
Contract strength	Can enforce behavior inside the CLI engine	Can guide or orchestrate behavior, but should not have to simulate native runtime guarantees
Relationship	Provides a stronger Codex engine	Composes and operates the engine

The intended boundary is:

• use Open Codex CLI for native runtime improvements that require changes in codex-rs, codex-cli, or the app-server protocol
• use wrapper/workflow projects for fast-moving orchestration, setup, prompts, skills, hooks, and project-specific operating policies
• keep the fork close enough to upstream that wrapper projects can treat it as a stronger Codex engine rather than a separate product family

Maintenance Philosophy

This fork is maintained with a conservative strategy:

• keep the fork close to upstream openai/codex
• merge upstream regularly rather than carrying a long-lived reimplementation
• keep fork-specific patches small, testable, and easy to reason about
• prefer user-facing CLI quality improvements over broad architectural churn
• document motivation, tradeoffs, and intended maintenance cost in the repo itself

In practice, maintenance will follow a straightforward loop:

1. track the latest upstream Codex CLI changes
2. merge upstream into this fork on a regular basis
3. re-validate the fork-specific delta
4. keep or refine only the patches that still provide clear value

The standard for changes here is simple: if a patch is not worth carrying across upstream merges, it does not belong in the fork.

Community

Issues and pull requests are welcome in this fork.

If you have a bug report, a CLI usability problem, a design idea, or a concrete patch, please open an issue or submit a PR. Small, focused, well-explained changes are preferred over broad, unrelated edits.

The intent of this repository is to keep development open and reviewable in public, even while the upstream repository remains invitation-only for external code contributions.

Compatibility Notes

This fork keeps the native Codex CLI implementation close to upstream, but the npm distribution uses fork-specific names so it can coexist with the official package:

• npm package: @leonw24/open-codex
• npm command: open-codex
• native binary identity: codex-cli

That means installing this fork from npm does not overwrite the official codex command from @openai/codex.

Quickstart

Option A: install from npm

The npm package is published under the leonw24 scope:

npm install -g @leonw24/open-codex
open-codex --version

The current npm payload is published for Linux x64. For other platforms, build from source until this fork publishes platform artifacts for macOS, Windows, and Linux arm64.

Option B: build from source

If you want to use this fork from source, build the Rust workspace and install the resulting binary locally.

# Clone the fork and build the CLI
git clone https://github.com/LEON-gittech/Open-Codex-CLI.git
cd Open-Codex-CLI/codex-rs
cargo build --release

Then choose one of these install modes:

Replace your local codex

mkdir -p ~/.local/bin
install -m 755 target/release/codex ~/.local/bin/codex

Install this fork as open-codex

mkdir -p ~/.local/bin
install -m 755 target/release/codex ~/.local/bin/open-codex

After that, run either codex or open-codex, depending on which install path you chose.

Docs

• Contributing
• Installing & building
• Open source fund

License

This repository is licensed under the Apache-2.0 License.

简体中文

背景动机

Codex CLI 是开源的，但上游仓库当前对外部代码贡献采用 invitation-only 策略。上游仓库在 docs/contributing.md 中写得很明确：没有被明确邀请的外部 PR 会被直接关闭，不进入正常 review 流程。

从上游维护者的角度，这个策略是可以理解的；但对于想要公开迭代、持续提交 CLI 改进、并让社区可以正常协作的人来说，这中间就出现了一个空白。这也是这个 fork 存在的原因。

Open Codex CLI 的目标不是为了分叉而分叉，而是在尽量贴近 upstream Codex CLI 的前提下，保留一层小而明确、容易理解、也容易持续维护的公开改动。

当前目标

• 解决我在实际使用 Codex CLI 时遇到的体验问题，不管它们是 bug，还是值得从 Claude Code 借鉴过来的 feature
• 持续优化 Codex CLI 在 zellij 下的使用体验（Fuck Off Tmux!）

当前相对最新 Upstream Codex CLI 的差异与路线图

这个 fork 目前基于最新的 openai/codex，并在最近几条 fork 自有 commit 的基础上增加了几项聚焦的 CLI 改进：

1. TUI 中通用的 user query 高亮优化

来自 commit c652bb8db1：

• 增加共享的 user_message_style()，用于 user-authored query surfaces，而不是继续保留 Zellij-only 的 transcript contrast 路径
• 把同一套 terminal-background-aware user-query highlight 同时用于聊天输入框 panel 和历史聊天里的 UserHistoryCell
• 历史 user query 会带 top/bottom divider lines，并保留醒目的 User › prefix，让长 transcript 里的用户提问更容易扫描
• 样式会根据 light/dark terminal background 自适应，而不是硬编码单一 foreground/border color

这是一个通用 TUI 可读性优化：聊天框中的当前 user query 和历史聊天中的旧 user query 使用一致的高亮语言，让用户输入回合更容易识别，而不再绑定到 zellij 场景。

2. TUI 中的 stale turn output 保护

来自 commit 67b06fd086：

• 在 live TUI notification/render boundary 增加 turn-aware filtering
• 丢弃属于旧 turn 的 assistant message、plan、reasoning deltas
• 丢弃 live thread-item notifications 中属于旧 turn 的 completed assistant/plan/reasoning items
• 忽略旧 turn 的 completion notification，避免旧 completion 结束当前 turn
• replay 路径保持独立，resumed thread snapshot 仍然可以渲染历史内容
• 增加针对 stale deltas、stale completed items、stale completions 的回归测试覆盖

这是一个偏正确性的修复：即使在 retry、replay、stream 时序比较复杂的情况下，UI 也不应该把错误 turn 的输出渲染出来。

3. 基于 upstream memories 的主动 memory staging

之前 fork-only 的 memory 子系统已经移除，以保持和 upstream memory 架构对齐。当前 memory 改动刻意收窄：

• upstream memory 仍是事实来源 — Codex 继续使用 upstream 的 memory_summary.md、MEMORY.md、topic 文件、skills 和 extensions/ad_hoc consolidation。memories feature 保留 upstream 的 experimental gate，默认不启用。

• 主动 staging tool — 启用 memory feature 后，Codex 暴露 memory_stage_update。它会把小型 ad-hoc note 写到 ~/.codex/memories/extensions/ad_hoc/notes/，供 upstream consolidation 后续吸收，同时把同一内容 staged 到当前 session。

• Session Memory Overlay — staged entries 会作为有预算上限的 developer-context overlay 注入当前 session，让新保存的信息不用等新 session 或后台 consolidation 就能影响下一轮。overlay 只在 revision 变化时发出。

• 明确的 staging 反馈 — memory_stage_update 现在会返回 staged content、可选 reason、overlay revision 和 ad-hoc note path，因此模型可以明确告诉用户本次写入了什么、为什么写入、以及 durable consolidation input 写到了哪里。

• 全局 overlay 诊断 — /memory-overlay 会展示所有 loaded session overlay entries 和全局 ad-hoc staged notes，并标出哪些内容已经在 durable memory 文件中出现 exact match。这是诊断视图，不是语义证明系统：未匹配的条目可能仍在等待 consolidation，也可能已经被 consolidation agent 改写表达。

• Overlay status metrics — /memory-overlay 的每一行会按来源分组（Session overlays 或 Ad-hoc staged notes），并带一个状态指标：matched 表示 staged content 已经在 durable memory 文件里出现 exact text match，pending 表示没有找到 exact durable match。匹配成功的行会展示 durable 文件路径，例如 MEMORY.md 或 topics/*.md。这让当前 durable visibility 可以被审计，但不会把 exact-match check 伪装成语义 consolidation 证明；显式 Phase 2 provenance（例如 selected/consumed but paraphrased）仍是后续需要补的 metric。

• Durable memory browser — /memory 会按 Summary、Overall index、Topics 展示当前 durable memory 内容，让用户可以直接检查下一次 session 真正会从 upstream memory 文件读到什么，而不是只靠 overlay diagnostics 推断 durable 状态。

• 已移除冲突 fork 行为 — 旧的直接 durable write tools、notepad 文件、topic frontmatter priority、merge-write 路径、自定义 AGENTS.md hierarchy 都不再属于当前 memory 实现。

这补上了主动更新缺口，同时保持 durable memory 存储和 consolidation 与 upstream 兼容。

4. 面向 Open Codex 的版本检测与升级提示

来自 commit e1e88af89d：

• 把 npm/bun 更新检测从 upstream Codex 元数据切换到 fork 的 @leonw24/open-codex
• 更新升级命令与 release notes 链接，使提示指向 Open Codex，而不是 @openai/codex
• 让运行时版本提醒与用户实际通过 npm 安装的包保持一致

这是一个 fork 正确性修复：版本提醒应该描述用户真正能安装的 Open Codex 版本，而不是 upstream Codex CLI 的发布流。

5. TUI 内建 session 导出

来自最近几条 fork 自有改动：

• 为当前 session 增加 /export <path>
• 支持用户自定义文件名，例如 /export talk.md 或 /export talk.txt
• 导出 markdown transcript，便于调试、归档和分享

这让类似 Claude Code 的会话导出能力直接进入 TUI，而不需要额外脚本或手工抓 transcript。

6. Reasoning effort 控制与单 turn 状态可见性

来自最近几条 fork 自有改动：

• 增加 /effort，可以直接在 TUI 中切换当前 reasoning effort
• 支持在用户 query 中用 standalone ulw、ultra 或 xhigh 触发单 turn xhigh reasoning
• marker 触发的 xhigh 保持 current-turn-only，不会修改 session 默认 effort
• 当前 foreground turn 处于 pending/running 时，model-with-reasoning status-line item 会显示这次提交实际使用的 per-turn effort
• turn 完成、失败或被打断后，status line 会恢复为 session/default effort

这补上了“请求实际按 xhigh 提交，但底部仍显示 high”的 UX 缺口：status line 会描述当前前台 turn，但不会把一次性的 marker 伪装成持久配置变更。

7. 轻量 /btw side questions

来自最近几条 fork 自有改动：

• 用 /btw <question> 快速提出 side question，不接管主聊天
• 在 BTW bottom pane 里继续短 follow-up，而不是把侧聊变成主任务
• 复用主 session 里用户熟悉的 model、effort、permission 和 tool 行为

这个能力适合“顺便问一下”的问题：它对当前工作有帮助，但不应该接管主任务线程。

8. Parallel-first subagent planning policy

通过 user-scope ~/.codex/AGENTS.md 指令层实现，并在 repo 中抽取了示例文件：docs/parallel-first-agent-execution.md。

• 显式覆盖 Codex 原本对 automatic agent spawning 的保守/禁止姿态，为复杂任务启用更激进的 subagent policy
• 在编辑前先按 independent investigation、review、test、docs、validation 等轴判断任务是否适合拆分
• 默认优先使用 read-only subagents 收集证据，除非 edit boundary 明确 disjoint，否则保留一个最终 implementation lane
• 保持稳定 profile 集合足够小（default、explorer、worker），用清晰的 task context 和 ownership 描述每个子任务
• 鼓励在 exploration、review、verification、release check 等阶段使用真正独立的 subagent lane

这不是硬编码 scheduler，而是 instruction-policy feature：它启用了更激进的 subagent 机制，同时避免多个执行 lane 争抢同一批文件。

9. 非阻塞后台执行

来自最近几条 fork 自有 TUI 改动：

这个能力围绕两个 background lanes 展开：

• Terminal commands — 长时间运行的 terminal session 会进入后台继续执行，不再通过前台 waiting / polling 阻塞主 turn。空的 command/exec/write 交互会保持 terminal backgrounded，因此 shell process 继续运行时也可以正常提交新的聊天输入。
• Subagents — 长时间运行的 agent work 会在 spawn/wait tool call 完成后作为 background activity 跟踪，能带上 agent nickname、role、status，以及可用的 progress lines。

共享交互模型是：

• Ctrl+B 把当前 terminal activity 送到后台，同时保留后续 streamed output。
• Down 打开实时 task panel，并区分 Tasks、Subagents、Terminals。
• Enter 打开详情，x 停止当前选中的 stoppable 后台项，Esc/Left 关闭 panel。
• status line 会把前台 Working 状态和后台 subagent/terminal 数量分开显示。
• terminal detail 展示运行时间和最近输出；subagent detail 展示 role、task、status、运行时间、progress 和任务边界信息。
• /agent 用于查看可用 agent profiles，/subagents 保留 subagent thread picker / 切换工作流。
• subagent 完成后会通过 core completion event 唤醒 parent turn，因此不需要手动调用 wait_agent 或关闭 agent 才能继续整合结果。
• completed subagent 到达 final state 后会从 spawn quota 中回收；当 spawn 没有可用 quota 时，主线程会先做 opportunistic cleanup 再返回 quota 不足。Interrupted subagent 仍会作为 active quota holder 保留，因为它们可能被 resume；因此 /subagents 的语义是 active/resumable subagent view，而不是僵尸 handle 列表。
• background command 完成后会保留输出到 history，但不会把任务重新拉回前台。

这是 Claude Code 风格体验背后的本质交互变化：后台工作仍然可见、可管理，但不会阻塞正常聊天流。

10. Status line token throughput visibility（Beta）

来自 commit 85e937b855：

• 增加可配置的 status-line item，用于显示 session-average input/output token throughput
• 当已经观察到足够的 token usage 和 turn duration 数据时，显示为 in <rate> / out <rate> tok/s
• 在还没有可用 sample 前，回退显示为 in -- / out -- tok/s
• 当前用 completed turn usage 和 duration 计算粗略 session average，并对 overlapping active windows 做 interval merging

这个能力目前标记为 Beta：它可以作为粗略 responsiveness signal，但还不是准确的 real-time throughput metric。

11. Status line 中显示 workspace git status

status line 现在可以通过可配置的 workspace-changes item 显示当前 workspace diff：

• 使用当前 workspace 的 Git numstat 数据，把 tracked changes 显示为 +<added>/-<deleted>
• 当存在 untracked files 时追加 ?<count>，因此即使文件还没 stage、也还没进入 tracked path 修改，也能看出 workspace 已经变脏
• clean workspace 下自动隐藏，避免没有改动时占用 status line 空间

这个能力是轻量级的上下文提示：它回答的是“当前 session 有没有留下本地改动”，不需要额外打开 shell 或 /status view。

近期路线图

接下来会优先推进几项面向 CLI 的改进：

1. Status line 中增加 token throughput 可见性 ✅ Beta

初步能力已经实现为 beta status-line item。剩余工作是准确性：当前 estimator 是 session-average 且依赖 turn timing，不应该当作精确的 real-time token throughput。

2. Session export ✅ 已完成

已实现类似 Claude Code 的 /export 会话导出能力，支持用户自定义文件名，例如 /export talk.txt 或 /export talk.md。当前已经覆盖调试、归档、分享这一类核心使用场景。

3. 更好的 memory 机制

当前已在 upstream memories 之上实现主动 memory staging（见上方当前差异第 3 项）。更广义的 durable-memory 行为应继续跟随 upstream，fork 侧只保留增量补充。主要剩余 observability gap 是原生 Phase 2 provenance metric：需要能区分 not selected yet、selected/consumed but paraphrased 和 exact durable match。

4. 更好的 Zellij 使用体验

继续针对 zellij 下的 Codex CLI 使用体验做优化，包括渲染、布局、对比度，以及其他与普通 terminal 或 tmux 表现不同的交互细节。

下一阶段重点

• 更好的 task management 体验

与外层封装项目的定位关系

Open Codex CLI 的定位是原生 Codex fork，而不是包在官方 CLI 外面的 wrapper layer。everything-claude-code 和 oh-my-codex 这类项目的价值在于可以用 TypeScript 或配置层快速迭代：skills、prompts、hooks、setup flows、agent teams，以及更高层的 workflow policy，都适合在 Rust runtime 外面快速演进。

这个 fork 针对的是互补的一层：必须在 Codex 本体里保证正确性的 source-level CLI behavior。比如 TUI rendering contract、turn routing、foreground/background task state、status-line truth、memory-session integration、app-server protocol surfaces、update detection 和 npm package identity。这些能力可以被 wrapper 项目编排和调用，但不应该靠 prompts 或 hooks 在外层模拟。

维度	Open Codex CLI	外层 wrapper/workflow 项目
主要层级	原生 Codex runtime 与分发层	围绕 Codex 或多种 coding agent 的外部编排层
典型实现方式	codex-rs 的 Rust 源码改动、codex-cli launcher/package 改动、protocol/schema 改动	TypeScript、shell scripts、配置文件、prompts、skills、hooks、MCP setup
最适合承载	TUI correctness、turn/session contracts、background task state、status-line truth、memory-session integration、app-server protocol、fork-aware updates	快速 workflow iteration、project setup、agent teams、prompt routing、skills、hooks、policy packs、跨工具约定
迭代速度	较慢，需要 Rust build、测试和 upstream merge 纪律	较快，可以通过 TS/config/prompt 层快速变化
Contract 强度	能在 CLI engine 内部强制保证行为	能引导和编排行为，但不应该模拟 native runtime guarantees
二者关系	提供更强的 Codex engine	组合、操作和扩展这个 engine

预期边界是：

• Open Codex CLI 负责那些需要改 codex-rs、codex-cli 或 app-server protocol 的原生 runtime 改进
• 外层 wrapper/workflow 项目负责快速变化的 orchestration、setup、prompts、skills、hooks 和项目级 operating policies
• fork 保持足够贴近 upstream，让 wrapper 项目可以把它当作更强的 Codex engine，而不是另一个完全独立的产品线

维护思路

这个 fork 的维护策略是偏保守的：

• 尽量保持与 upstream openai/codex 接近
• 通过持续 merge upstream，而不是长期走大幅重写路线
• 保持 fork 自有 patch 小而清晰、可测试、可解释
• 优先关注面向 CLI 用户的真实体验改进，而不是无边界扩张
• 在仓库内直接记录动机、取舍和维护成本

实际维护会遵循一个比较直接的循环：

1. 跟踪 upstream Codex CLI 的最新变化
2. 定期把 upstream merge 进这个 fork
3. 重新验证 fork 的自有差异是否仍然成立
4. 只保留那些在持续 merge 成本下仍然值得维护的 patch

标准很简单：如果一个 patch 不值得长期跟随 upstream 一起维护，它就不应该存在于这个 fork 中。

社区协作

这个 fork 欢迎 issue 和 pull request。

如果你有 bug report、CLI 可用性问题、设计想法，或者已经有一个清晰的小 patch，都欢迎直接提 issue 或 PR。相比大而杂的改动，这里更偏好小范围、聚焦、说明充分的提交。

这个仓库的目标之一，就是在 upstream 仍然对外部代码贡献采用 invitation-only 策略的情况下，继续保持公开、可 review、可协作的开发方式。

兼容性说明

这个 fork 的原生 CLI 实现尽量贴近 upstream，但 npm 分发使用 fork 自己的命名，这样可以和官方包共存：

• npm 包名：@leonw24/open-codex
• npm 命令名：open-codex
• 原生二进制身份：codex-cli

也就是说，通过 npm 安装这个 fork 不会覆盖官方 @openai/codex 提供的 codex 命令。

Quickstart

方式 A：通过 npm 安装

npm 包发布在 leonw24 scope 下：

npm install -g @leonw24/open-codex
open-codex --version

当前 npm payload 已发布 Linux x64 版本。macOS、Windows 和 Linux arm64 在发布对应平台 artifact 之前，请先使用源码构建方式安装。

方式 B：从源码构建

如果你想从源码使用这个 fork，可以先构建 Rust workspace，再把产出的二进制安装到本地。

# 克隆仓库并构建 CLI
git clone https://github.com/LEON-gittech/Open-Codex-CLI.git
cd Open-Codex-CLI/codex-rs
cargo build --release

然后在下面两种安装方式中选一个：

直接覆盖你本地的 codex

mkdir -p ~/.local/bin
install -m 755 target/release/codex ~/.local/bin/codex

并行安装为 open-codex

mkdir -p ~/.local/bin
install -m 755 target/release/codex ~/.local/bin/open-codex

之后根据你的安装方式，运行 codex 或 open-codex 即可。

文档

• Contributing
• Installing & building
• Open source fund

许可证

本仓库使用 Apache-2.0 License。