Skip to content

v0.2.3

Latest

Choose a tag to compare

@houyhlouis houyhlouis released this 17 Nov 15:38

The first release since v0.1.1. It contains the stability and feature work of 0.2.0, based on a full audit of v0.1.1, and the Windows and macOS fixes of 0.2.1 to 0.2.3, found by the CI runs on those systems. Stop the old broker before you update (server.py stop), then restart your MCP client. The state database is upgraded automatically at the first start, after a backup copy is saved next to it.

Highlights

  • Safer approvals: a file approval checks every path of the patch and is tied to the exact patch that was shown. A patch with hidden credential-like values can only be accepted by a person. Answers are only sent to a conversation that has been verified again after a restart.
  • A project stays reserved while anything can still run in it: a turn, a background terminal, an active goal or a queued instruction. After a restart, a task that was working keeps its project until you have checked and called codex_resume. On Linux, leftover Codex sandbox processes also keep it reserved.
  • Results you can check: codex_get with view: "result" separates what Codex said from the commands and file changes it reported, with artifacts checked by hash. codex_resume returns a report of what is known and unknown after a restart. Nothing is ever repeated automatically.
  • Clear errors: every failed call returns a stable error.code with retryable, uncertain and next_steps.
  • New operator commands: doctor (checks the installation without starting anything), backup, prune (reviewed plan first) and incident-export (the structure of a task without its content).
  • New tools for parallel work: codex_worktrees (Git worktrees, off by default), codex_plans (small dependency plans) and family budgets. 34 tools in total.
  • MCP 2026-07-28 with approval forms and the Tasks extension, alongside all earlier revisions.
  • Windows and macOS (0.2.1 to 0.2.3): private folders created by Python 3.13 or newer, worktrees and prune work on Windows; a stopped pipe server releases its Windows handles at once instead of at the next garbage collection; worktree commands start half as many Git processes; a worktree name Git cannot use as a branch is refused up front.

Upgrading

python3 server.py stop      # Windows: py -3 server.py stop
git pull                    # or download this release's "Source code (zip)"

Then restart Claude Code or your MCP client. Saved tasks and history are kept.

  • Stop the broker when no task is working. A task that was interrupted by the stop keeps its project until you call codex_resume for it.
  • The first start upgrades the state database (layout 11). It first writes a full copy next to it, state.sqlite3.pre-v1-*.bak, so make sure there is enough free disk space. A large database took under a second.
  • If you use the agent instructions from examples/CLAUDE.md, copy the new version: it describes the new results, errors, worktrees, plans and budgets.
  • Optional settings: worktrees = true, sandbox_process_check = false (Linux), and a default [budget]. See docs/configuration.md.

Requirements

Python 3.11 or newer, and the OpenAI Codex CLI 0.167.0 or newer with a working sign-in. No other dependencies. Worktrees need Git 2.36 or newer.

Tested

  • 1,266 offline tests on Windows, macOS and Linux with Python 3.11 and 3.14 (GitHub Actions; 83 in 0.1.1).
  • The official MCP Python SDK 1.26.0, package builds (wheel and sdist) and the protocol schema of Codex CLI 0.167.0.
  • Live tests against Codex CLI 0.167.0 on Linux: all five live scripts, restarts with running work, updates from 0.1.1 (also with a 274 MB database), budgets, worktrees and plans.
  • Not tried yet: a real MCP 2026-07-28 client.

Installation guide · Full changelog · Documentation