codex-workflow

codex-workflow turns repeatable Codex work into reusable local workflows.

It is for developers who already use Codex in a repository and want a better way to run the same kinds of work again: investigate a bug, plan and implement a change, review docs, check release readiness, or recover a paused run without piecing together terminal scrollback.

Run it from a repo:

codex-workflow

The default screen is a terminal operator shell. It shows the workflows available for the current repo, recent runs, the selected workflow details, model policy, and the next actions you can take.

Why Use It

Use codex-workflow when you want Codex work to be:

• repeatable, because prompts live in named workflow files
• recoverable, because every run writes durable local state
• reviewable, because status, results, logs, model policy, and evidence are saved
• safer to operate, because write-capable runs require an explicit --write
• easier to start, because the no-arg command lets you choose, edit, run, resume, or inspect from one place

It is not a distributed job system or a general DAG orchestrator. A workflow is a local, ordered sequence of Codex prompts for one repository.

Install

Requirements:

• Node >=18.18.0
• the codex CLI on PATH
• a local Codex login/config that can start codex app-server

Most users do not need Rust or Go. The npm package includes native renderer artifacts for supported platforms; maintainers only need those toolchains when building renderers locally.

Install the published package:

npm install -g @onetool/codex-workflow
codex-workflow version

Install a release candidate when the next dist tag is available:

npm install -g @onetool/codex-workflow@next
codex-workflow version

Run from this repository during development:

npm install
node src/cli.js

Start Here

Open a repository:

cd /path/to/repo
codex-workflow

You can also point at a repo from anywhere:

codex-workflow --cwd /path/to/repo

From the operator shell:

• Tab moves between workflows and runs
• arrow keys move inside the focused list
• Enter runs the selected workflow or inspects the selected run
• e edits the selected workflow
• n creates a workflow
• p, m, and R set launch model policy
• r resumes the selected run
• ? opens help
• q quits

If the terminal cannot run the rich shell, codex-workflow falls back to a plain transcript interface. The workflow behavior and run records stay the same.

For scripts, use the JSON home summary:

codex-workflow home --cwd /path/to/repo --json

Run A Workflow

Run a bundled workflow:

codex-workflow run inspect-fix-verify --cwd /path/to/repo

Pass task context to prompts that use {{input}}:

codex-workflow run inspect-fix-verify \
  --cwd /path/to/repo \
  --input "Fix the flaky cache invalidation test"

Run with write access:

codex-workflow run inspect-fix-verify --cwd /path/to/repo --write

Run in the background:

codex-workflow run inspect-fix-verify --cwd /path/to/repo --background

Check what happened:

codex-workflow status
codex-workflow inspect
codex-workflow result

Resume or stop a run:

codex-workflow resume
codex-workflow cancel

Compare two attempts:

codex-workflow compare <left-run-id> <right-run-id>

Bundled Workflows

The package includes starter workflows for common Codex sessions:

• inspect-fix-verify: investigate a problem, fix it, and verify the result
• plan-implement-review: plan a change, implement it, then review it
• docs-audit: find and fix documentation gaps
• bug-triage-to-patch: turn a bug report into a patch path
• refactor-with-guardrails: refactor while preserving behavior
• commit-gated-implementation: keep commit actions explicitly human-approved
• release-readiness: check whether a change looks ready to ship

List the workflows visible from the current repo:

codex-workflow list

Create Your Own Workflow

Workflow lookup is repo-first. Project workflows live in:

.codex/workflows/

Create one:

codex-workflow new release-check --cwd /path/to/repo

Edit it in the terminal workflow editor:

codex-workflow edit release-check --cwd /path/to/repo

Validate and preview before running:

codex-workflow show release-check --cwd /path/to/repo
codex-workflow validate release-check --cwd /path/to/repo
codex-workflow diff release-check --cwd /path/to/repo

Workflows are TOML files. A small workflow looks like this:

title = "Release Check"
version = "1"

[[steps]]
id = "scope"
label = "Scope"
prompt = "Summarize the change, touched areas, and expected release criteria."

[[steps]]
id = "risk"
label = "Risk"
prompt = "Review tests, docs, config, migrations, and rollback risks. Use {{input}} as extra context."

[[steps]]
id = "decision"
label = "Decision"
prompt = "State whether the change appears ready and list any blockers."

See Workflow Authoring and Workflow Format Reference for the full schema.

Model Policy

Runs can inherit Codex defaults or use explicit model and reasoning choices.

Set a one-off policy from the CLI:

codex-workflow run inspect-fix-verify \
  --cwd /path/to/repo \
  --model gpt-5.4-mini \
  --reasoning-effort medium

Set policy from the operator shell with:

• p for guided presets
• m for a custom model
• R for reasoning effort

Workflow files can also define defaults and per-step prompt policy. The run record captures the requested and effective policy, and records actual model information when Codex exposes it.

Per-run CLI flags override workflow defaults and step policy. Use workflow policy for repeatable defaults, and use CLI or operator-shell policy for one-off experiments.

Safety And Recovery

codex-workflow keeps execution local and delegates sandbox enforcement to Codex.

• runs default to read-only
• --write requests workspace-write execution from Codex
• paused, failed, and background runs can be inspected later
• operator actions such as pause, steer, approve, reject, and retry are written to the run record

Run records are stored under:

~/.codex/workflow-runs/<run-id>/

Useful files:

• state.json: normalized run state, step state, recovery state, and model policy
• events.jsonl: ordered runtime events
• console.log: transcript output for background runs

Workflow Studio

Workflow Studio is a local browser companion for authoring and review:

codex-workflow studio inspect-fix-verify --cwd /path/to/repo

Use it when a browser layout is more comfortable for workflow editing, launch preview, run comparison, evidence review, or notes. The terminal shell and Studio use the same workflow files and run state.

Current Support

Supported:

• CLI install and command surface
• no-arg operator shell
• Rust TUI on supported interactive Unix-like terminals
• transcript output for non-interactive, background, and explicit transcript use
• readline fallback for unsupported interactive terminal use
• JSON output for scriptable commands
• terminal workflow authoring
• Workflow Studio companion
• background runs and local recovery

Experimental:

• Go renderer

Out of scope:

• branching or DAG workflows
• distributed workers or brokered execution
• automatic retry policy engines
• runtime enforcement of external commit or release policy
• stable public JavaScript library API

See Support Matrix for platform details.

Common Commands

codex-workflow
codex-workflow home --json
codex-workflow list
codex-workflow run <workflow> --cwd <path>
codex-workflow run <workflow> --cwd <path> --write
codex-workflow status [run-id]
codex-workflow inspect [run-id]
codex-workflow result [run-id]
codex-workflow resume [run-id]
codex-workflow cancel [run-id]
codex-workflow compare <left-run-id> <right-run-id>
codex-workflow new <name>
codex-workflow edit <name|path>
codex-workflow validate <name|path>
codex-workflow diff <name|path>
codex-workflow studio [workflow]

If a workflow name matches a command name, run it explicitly:

codex-workflow run home

Troubleshooting

codex app-server is unavailable:

• confirm codex is installed and on PATH
• confirm Codex is authenticated
• run codex app-server directly to see the Codex-side error

The rich terminal UI does not start:

• use --ui transcript for the plain interface
• confirm you are in an interactive terminal
• run codex-workflow home --json for a machine-readable health summary

A run fails or pauses:

codex-workflow inspect
codex-workflow resume
codex-workflow cancel

Documentation

• Getting Started
• Running Workflows
• Workflow Authoring
• Workflow Studio
• Recovery and Troubleshooting
• Support Matrix
• CLI Reference
• Workflow Format Reference

Maintainer docs live under docs/maintainers/, including the long-lived Design Tenets.