codex-flow

KO | EN

gitlite — search

#automation #redis #graphql #macos #tensorflow #vue #gpt #devops #terminal #editor

(★ 9)

Dynamic workflow orchestration for Codex: parallel, resumable, journaled sub-agents for complex tasks.

File Explorer

ZIP Download

- - bug_report.md
  - feature_request.md
- - ci.yml
  - publish.yml
- PULL_REQUEST_TEMPLATE.md
- codex-exec.ts
- codex-sdk.ts
- fake.ts
- openai-responses.ts
- registry.ts
- stream-errors.ts
- types.ts
- codex-flow-banner.svg
- codex-flow-demo.gif
- codex-flow-demo.svg
- codex-flow.mjs
- dongt.mjs
- doctor.ts
- init.ts
- install-codex.ts
- main.ts
- progress.ts
- run.ts
- smoke.ts
- try.ts
- - openai.yaml
- - engine-api.md
  - setup.md
- SKILL.md
- - openai.yaml
- - audit-method.md
  - audit-template.workflow.ts
- SKILL.md
- - openai.yaml
- - fix-method.md
  - fix-template.workflow.ts
- SKILL.md
- CODEX_APP_CLI.md
- CODEX_FOR_OSS_APPLICATION.md
- FAQ.md
- LAUNCH_PLAYBOOK.md
- MAINTAINER_OPERATIONS.md
- POSITIONING.md
- PROMPTS.md
- agent.ts
- budget.ts
- canonical.ts
- cli.ts
- determinism.ts
- index.ts
- journal.ts
- runtime.ts
- schema.ts
- semaphore.ts
- topologies.ts
- types.ts
- bug-investigation.workflow.ts
- business-audit.workflow.ts
- hello.workflow.ts
- issue-triage.workflow.ts
- parallel-fix.workflow.ts
- pong.workflow.ts
- pr-review.workflow.ts
- README.md
- release-smoke.workflow.ts
- triage.workflow.ts
- e2e.ts
- smoke.ts
- cli.test.ts
- engine.test.ts
- examples.test.ts
.gitignore
AGENTS.md
CHANGELOG.md
codex.config.json
CONTRIBUTING.md
DESIGN-codex-dynamic-workflow.md
index.d.ts
index.mjs
LICENSE
package-lock.json
package.json
README.md
ROADMAP.md
SECURITY.md
tsconfig.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

Release Visit
License: MIT Visit
Node >=18 Visit
Codex App / CLI Visit
codex-flow banner

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Turn one natural-language request in Codex App or Codex CLI into **parallel, resumable, journaled Codex sub-agents**.

## Install in 30 seconds

```bash
npm install -g codex-flow
codex-flow install-codex
codex-flow doctor
# restart Codex App or Codex CLI
```

Then open **any** project in Codex and say:

> 用动态工作流帮我排查登录失败的问题
>
> use a dynamic workflow to investigate this bug in parallel

GitHub fallback if npm is unavailable: `npm install -g github:Dmatut7/codex-flow`.
`dongt` remains as a compatibility alias, but the public package and docs use `codex-flow`.

## Update installed Codex skills

When `codex-flow` ships updated skills, update both the npm package and the copied Codex skills:

```bash
npm install -g codex-flow@latest
codex-flow install-codex
codex-flow doctor
# restart Codex App or Codex CLI
```

Why both steps? `npm install -g` updates the CLI package; `codex-flow install-codex` copies the bundled skills into `~/.codex/skills`.
Codex reads those installed skill files after restart.

## What it feels like

![codex-flow animated demo](https://raw.githubusercontent.com/Dmatut7/codex-flow/main/assets/codex-flow-demo.gif)

The important difference is not another config file. It is the loop:

1. install once,
2. say a normal sentence in Codex,
3. Codex generates a temporary workflow,
4. `codex-flow` runs the branches in parallel,
5. the journal makes interruption and rerun cheap.

Prefer a static version? See the [storyboard SVG](assets/codex-flow-demo.svg).

## Why maintainers use it

Built for maintainers and power users who do repeated multi-file work:

- **Bug investigations** — one hypothesis or file group per Codex sub-agent.
- **PR / code review** — fan out review passes, then merge findings.
- **Issue triage** — classify, reproduce, and propose next actions in parallel.
- **Release smoke checks** — run repeatable checks with journaled evidence.

Codex (via the installed skill) will:

1. decide the task suits a dynamic workflow,
2. **generate** a temporary workflow under `.codex-flow/generated/`,
3. **run** it (`codex-flow run …`) — many Codex sub-agents in parallel,
4. **summarize** the result.

It uses **your Codex / ChatGPT membership login** — no OpenAI API key needed.

If the run is interrupted (Ctrl-C, crash, budget), running it again **resumes**: finished work replays instantly, only unfinished nodes call Codex again.

If this is useful, star the repo so more Codex users can find it: [Dmatut7/codex-flow](https://github.com/Dmatut7/codex-flow).

See [how to use it in Codex App / CLI](docs/CODEX_APP_CLI.md), the [FAQ](docs/FAQ.md), the [prompt gallery](docs/PROMPTS.md) for copy-paste Codex prompts, and the [maintainer workflow gallery](examples/README.md) for import-free runnable bug investigation, PR review, issue triage, and release smoke workflows. See [docs/POSITIONING.md](docs/POSITIONING.md) for what `codex-flow` is / is not, [ROADMAP.md](ROADMAP.md) for public next steps, and [docs/LAUNCH_PLAYBOOK.md](docs/LAUNCH_PLAYBOOK.md) for sharing / launch copy.

## Why this is more than "an engine"

A normal Codex turn is linear. `codex-flow` makes Codex orchestrate:

- **parallel fan-out** — one sub-agent per file / hypothesis / item, all at once,
- **content-addressed resume** — re-run = free replay of completed work,
- **journaling / audit** — every node + token usage recorded in `.codex-flow/journal/*.jsonl`,
- **soft token budget**, deterministic control flow, schema-validated outputs.

## Manual use (optional)

You can also run a workflow file directly:

```bash
codex-flow run path/to/my.workflow.ts                 # default backend: codex-sdk (your membership)
codex-flow run path/to/my.workflow.ts --backend fake  # no network, for testing
```

A workflow is a single file that exports a default function. The skill generates these for you, but here is the shape (import-free, plain JSON Schema):

```ts
export default async function workflow(ctx) {
  const { agent, parallel, phase, log } = ctx;
  const Schema = {
    type: "object", additionalProperties: false,
    required: ["file", "suspect", "confidence"],
    properties: { file: { type: "string" }, suspect: { type: "string" }, confidence: { type: "number" } },
  };
  const files = ["src/auth/login.ts", "src/auth/session.ts"];
  const findings = await phase("investigate", async () =>
    parallel(files.map((file) => async () =>
      (await agent(`Investigate ${file} for the login bug; report the suspect + 0..1 confidence.`,
        { schema: Schema, sandbox: "read-only" })).output))
  );
  log("findings", findings);
  return { findings: findings.filter((f) => f && f.confidence >= 0.5) };
}
```

Full API + rules: `codex-skill/references/engine-api.md`.

## Engine primitives

`ctx.agent(prompt, opts)` (one sub-task), `ctx.parallel(thunks)` (barrier fan-out), `ctx.pipeline(items, ...stages)` (per-item, no barrier between stages), `ctx.phase(title, body)`, `ctx.log(msg, data)`, `ctx.now()` / `ctx.random()` (deterministic), `ctx.budget`.

Key `agent` opts: `schema` (Zod or JSON Schema → strict JSON output), `sandbox` (`read-only` | `workspace-write` | `danger-full-access`), `cwd` (required for writable nodes), `backend`, `timeoutMs`, `retries`, `nodeKey`.

Use `ctx.now()` / `ctx.random()` for control flow — never wall-clock or ambient RNG to decide which nodes exist.

## Programmatic use (optional)

The project is CLI-first, but the package also exports the engine:

```js
import { createEngine } from "codex-flow";

## Backends and routing

- `codex-sdk` (default): in-process Codex SDK thread, uses your membership login.
- `codex-exec`: spawns `codex exec --json` for hard process isolation.
- `openai-responses`: direct Responses API with strict JSON — **needs `OPENAI_API_KEY`** (separate from a Codex membership). Optional cheap fast-path.
- `fake`: deterministic, no network — for tests.

Routing: `opts.backend` wins → else (if `autoRoute`) an explicitly `pure`/`kind` schema-only node may use `openai-responses`, an `isolate:true` node uses `codex-exec` → else `defaultBackend`. The engine never infers "pure" from a missing `cwd`.

## Config

Per-project overrides go in `.codex-flow/config.json`; the engine-level config (also used by `createEngine`) supports:

- `defaultBackend`, `autoRoute`, `concurrency`, `hardMaxConcurrency`, `providerRateBudget`
- `seed` (deterministic `now`/`random` + shadows), `defaultModel`, `estimatedTokensPerCall`, `timeoutMs`
- `transientRetries`, `transientBaseMs` (429/5xx/network retry, separate from schema repair)
- `budget.maxTokens` / `budget.maxNodes` / `budget.onExceeded` (`throw` | `skip` | `downgrade`)
- `adapters.codexSdk` (→ `new Codex`), `adapters.codexExec` (`codexPath`, `env`, `graceWindowMs`), `adapters.openaiResponses` (→ `new OpenAI`), `adapters.fake`

## Resume / replay

Automatic. Completed terminal nodes replay by `cacheKey` (prompt + validation schema + model + resolved cwd + sandbox + structural position + dependency `prevKey`). The key excludes backend identity, thread id, signal, timestamps, jitter, env, wall-clock, and repair text. Replayed nodes don't call the backend or charge budget. A torn trailing journal line is dropped; a node whose journal ends on a non-terminal repair record re-runs.

## Determinism boundary

During a run, the workflow gets seeded shadows for `Date`, `Date.now`, `Math.random`, `performance.now`, `process.hrtime`, and `crypto.randomUUID`/`getRandomValues`. Best-effort: deps that captured real globals at import time can still leak — keep control flow on `ctx.now()`/`ctx.random()`.

## Verify it on real Codex

```bash
codex-flow smoke --backend codex-sdk     # one real structured call
codex-flow smoke --backend codex-exec
```
Missing credentials prints `SMOKE_SKIPPED` and exits 0.

## Develop / test

```bash
npm run typecheck
npm test            # FakeAdapter only, no network
```

Regression suite covers keyed replay, dependency-subtree invalidation, schema repair, transient retry, writable-cwd protection, deterministic shadows + stable cache keys, soft-budget skip, crash-residue / non-terminal-repair journal recovery, backend routing, and the CLI (`install-codex` + `run`).

See [CONTRIBUTING.md](CONTRIBUTING.md) for local development rules, [docs/MAINTAINER_OPERATIONS.md](docs/MAINTAINER_OPERATIONS.md) for release / skill update operations, and [docs/CODEX_FOR_OSS_APPLICATION.md](docs/CODEX_FOR_OSS_APPLICATION.md) for the Codex for Open Source application prep notes.

codex-flow

Owner Repos

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

codex-flow

Owner Repos

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README