Skip to content

Releases

v0.2.3

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

v0.1.1

Choose a tag to compare

@houyhlouis houyhlouis released this 09 Nov 14:54

Bug-fix release. After updating, run server.py stop once and restart your MCP client, so that the new version of the background broker starts.

Highlights

  • Windows: server.py stop now waits until the broker has really exited, so its files can be deleted or replaced straight away. This was the cause of the Windows CI failures. The broker also no longer stops answering after a client disconnects early, and no longer rewrites its folder permissions on every request.
  • Security: the default codex_binary = "codex" is looked up on PATH only. Before, a file named codex in the MCP client's current folder (often your project) was run instead of the installed Codex CLI.
  • Approvals: the main agent can now deny requests in every documented format, and permission grants with relative paths inside the project work.
  • Documentation: the README (English and Chinese) has a step-by-step installation guide, and the docs are a smaller set of clearer guides.

All fixes

  • stop returned while the broker process still held broker.log open (WinError 32 on Windows when deleting or replacing files).
  • The Windows named-pipe listener stopped for good when a client connected and left before being accepted (ERROR_NO_DATA); one shutdown path closed a pipe handle twice.
  • The Windows state folder's permissions were rewritten through the whole folder on every request.
  • A file named codex in the current folder could run instead of the installed CLI (on Windows, shutil.which also searches the current folder first).
  • The denials {"permissions": {}, "scope": "turn"} and {"action": "decline", "content": null} were refused with "Human review required".
  • Relative paths in permission grants were resolved against the broker's working directory instead of the project.
  • service_tier: "default" was sent to Codex as if it were a tier; it now clears the tier.
  • Retrying a failed request_id said "inspect task None"; it now shows the original error.
  • Lock files are unlocked before closing; rejected Unix connections no longer log tracebacks; review forms accept questions without a header; a missing toolchain_paths entry gives a clear error.

Other changes

  • Version 0.1.1: a client from another version refuses an old broker and explains how to stop it.
  • --version and help text for every command; stop prints {"stopped": true, "pid": …} once the broker has exited.
  • 8 new regression tests (83 in total). CI also byte-compiles the sources and tests pip install ..

Upgrading

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

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

Requirements

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

Tested

  • 83 offline tests on Windows, macOS and Linux with Python 3.11 and 3.14 (GitHub Actions).
  • The official MCP Python SDK 1.26.0.
  • Live tests against Codex CLI 0.167.0 on Linux.

Installation guide · Full changelog · Documentation