dev-flow-codex

中文 | English

dev-flow-codex lets Codex continue long-running coding work from a local durable Task while keeping scope, verification budget, and delivery conditions explicit. Codex still reads repositories, edits files, and runs commands; the bundled Go Core retains the current stage, limits verification expansion, invalidates stale records, and returns a next step, Recovery assessment, or explicit blocker after repository drift or an uncertain Action result.

Support

Item	Current support
Package	dev-flow-codex
Stable platform	macOS arm64
Current-source platform	macOS arm64 (darwin-arm64); Windows 10/11 desktop x64 (win32-x64)
Node.js	>=24
Codex	>=0.147.0
Releases	GitHub Releases

Stable support is defined by the Support Matrix. Capability on main may not yet be present in npm @latest. Windows Server, 32-bit Windows, Windows ARM64, and Intel Mac are outside the current-source support boundary. The launcher rejects runtime pairs other than darwin-arm64 and win32-x64.

Install

Use the unified lifecycle entry:

npm install -g @imotong/dev-flow@latest
dev-flow

The installer installs the Codex package, registers the Plugin and MCP, and reads back readiness. Native Host commands remain for diagnosis and recovery:

npm install -g dev-flow-codex@latest
dev-flow-codex setup
dev-flow-codex status --json
dev-flow-codex --version

When fixed user configuration is absent, setup creates $HOME/.dev-flow/config.json on macOS or %USERPROFILE%\.dev-flow\config.json on Windows, validates the package, bundled Core, and Codex compatibility, then registers the marketplace, Plugin, and MCP. Windows Task data defaults to %LOCALAPPDATA%\dev-flow\data. See the Command Reference for every argument and machine-readable result.

After setup, review and trust the Dev Flow packaged hook through Codex /hooks. Codex skips the apply_patch write-before check until that hook is trusted.

Start a Task

From a Git repository, describe a bounded implementation, bug fix, refactoring, targeted-testing, or development-delivery request. Codex can select Dev Flow automatically. Use the exact selector when you want to enter explicitly:

$dev-flow-codex:dev-flow Fix idempotency in the order-creation endpoint and run targeted tests.

This is not a shell command. $dev-flow is not an alias. Explanation-only, status-only, design-discussion, ordinary-question, and ambiguous requests do not automatically create or resume a Task.

A new Task begins in requirements and retains the original request, scope, acceptance criteria, and verification budget. plain, spec-kit, or openspec may be selected at creation, but there is no OpenSpec / Spec Kit artifact importer today.

Resume an existing Task

Return to the same participating physical worktree and continue the original request in a new Codex session, or use the exact selector. The Adapter reads Core first and restores the current stage, revision, scope, remaining verification, Blocker, and Recovery state instead of rebuilding progress from chat.

If the previous Action response was lost or truncated, the Adapter reads the current Task and Recovery assessment before continuing, recovering, blocking, or retrying safely. It does not replay the original submission on its own.

When the same failure, the same test result, or the same changed-path and failure loop appears three times, Core retains the third result and pauses the Task. Codex does not resolve that blocker automatically. After the developer explicitly chooses another approach or allows one more attempt, the Adapter resolves the blocker and continues from Core's retained resume stage. Another exact repetition pauses the Task again.

Ask before an out-of-scope file write

The Plugin bundles a PreToolUse hook. After the developer trusts the current hook through Codex /hooks, every apply_patch call sends its target files to the packaged Core before execution through the package-owned dev-flow-codex hook pre-tool-use launcher on PATH, which parses the event and uses the internal host-check pre-file-write entrypoint. The launcher resolves the package-local Core without depending on the Codex Plugin cache layout. Core uses the union of every WorkItem's ExpectedPaths in the current Task Plan, with repository-key qualification for multi-repository Tasks. An expected file in additional repository B or C proceeds without a question when the repository is already in Task Repository Scope and authorized through --add-dir; being outside working directory A is not itself out of scope.

An unplanned file pauses the Task before apply_patch runs. The developer chooses allow_once for that same write intent, expand_scope to return to TASKS, or reject for the current Task Plan revision. Core retains the choice and reason. Before testing and DONE, Core also reconciles all Task-introduced paths.

The hook does not parse Bash, external processes, or specialized tools that bypass Codex tool hooks; those writes may be found only by Core's final check. An untrusted, disabled, or unavailable hook must not be presented as reliable write-before interception.

Inspect status

Inspect package and registration state:

dev-flow status --host codex
dev-flow-codex status --json

Inspect Tasks, current stage, timeline, Recovery, and Blocker:

dev-flow webui start

The WebUI is local loopback only. See WebUI for details.

Remove

Use the unified entry for the recommended Codex uninstall. The native data-preserving sequence is:

dev-flow-codex remove
npm uninstall -g dev-flow-codex

remove validates the runtime receipt and stops the matching WebUI before removing the package-owned Plugin, marketplace registration, and receipt. A stop failure retains later objects. Task data and the target Git repository are retained by default, so installing a compatible package and running setup can resume existing Tasks.

Permanent data cleanup is a separate dev-flow factory-reset flow and requires strong confirmation from its current plan. Do not manually delete an uncertain data directory.

Codex permission and product boundaries

• repository access remains controlled by Codex and user authorization; Dev Flow does not expand the sandbox;
• Core observes Git read-only and does not commit, push, merge, rebase, tag, or publish;
• Codex edits files and runs commands; the Host hook checks apply_patch and Core reconciles cumulative paths, but does not intercept every operation;
• the selector does not bypass repository permission, the current Action, Git-mutation authority, or release confirmation;
• optional code indexing assists retrieval only and cannot expand Scope or decide Recovery and process state.

Advanced multi-repository and worktree use

Current source supports one primary repository and up to seven explicit additional repositories. Each additional repository must first be authorized as a writable root for the session through Codex --add-dir. Scope is immutable after creation, and neighboring directories are not discovered automatically.

For an explicit parallel batch, or when a new request meets ACTIVE_TASK_CONFLICT, Codex dispatches an isolated Task only when the Host provides worktree-backed task/thread creation. A child starts from committed default-branch state and receives no uncommitted changes from the occupied checkout. Core does not create, switch, merge, or clean worktrees.

Check Project Status before assuming these capabilities are in the stable artifact. Exact Repository Scope, worktree dispatch, and protocol behavior live in Architecture and the Command Reference.

Related documentation

• Product Definition
• Interruption-and-resume demo
• Command Reference
• Architecture
• Project Status
• WebUI