Codex acts as the host planner, reviewer, and final acceptance authority
Reasonix, Claude Code, or Agy executes implementation and fixes in the same session
The workflow maintains atomic state, Git baseline gates, scope enforcement, and convergence limits

Prerequisites

Node.js >= 20
Git repository
At least one executor: Reasonix, Claude Code, or Agy

Installation

npm install -g agent-workflow

Or use locally in a project:

npm install --save-dev agent-workflow

Quick Start

Create a plan (WorkflowPlanV1 JSON):

{
  "version": "1",
  "title": "Add user authentication",
  "planMarkdown": "Implement JWT-based authentication with login and logout endpoints.",
  "scope": ["src/auth/", "src/routes/auth.ts"],
  "acceptanceCriteria": [
    "Login endpoint returns valid JWT",
    "Protected routes reject unauthenticated requests",
    "All tests pass"
  ],
  "verificationCommands": [
    ["npm", "test"],
    ["npm", "run", "lint"]
  ]
}

Start a workflow:

agent-workflow start --plan plan.json --executor reasonix

Review the implementation:

agent-workflow review --run <run-id>

Submit a decision (fix, accept, or needs_human):

agent-workflow decide --run <run-id> --input decision.json

Commands

`agent-workflow start`

Start a new workflow run. Requires a clean working tree.

agent-workflow start --plan <plan.json|-> --executor <reasonix|claude|agy> [--max-cycles <n>]

`agent-workflow review`

Generate a Codex review bundle after executor completion. Checks HEAD stability and scope compliance.

agent-workflow review --run <run-id>

`agent-workflow decide`

Submit a Codex decision (fix, accept, or needs_human). A fix decision resumes the same executor session.

agent-workflow decide --run <run-id> --input <decision.json|->

`agent-workflow retry-review`

Retry review after the executor has removed approved out-of-scope artifacts.

agent-workflow retry-review --run <run-id>

`agent-workflow retry-execute`

Retry executor resume after clearing an external session conflict.

agent-workflow retry-execute --run <run-id>

`agent-workflow status`

Display current workflow status.

agent-workflow status --run <run-id> [--json]

When the workflow is executing, additional live fields are shown:

Executor PID — process ID of the running executor
Elapsed — running time
Activity — current operation being performed
Last activity — timestamp of most recent output
Log bytes — bytes written to the attempt log so far
Live log — path to the streaming log file

`agent-workflow logs`

Tail and follow live executor output for a running workflow.

agent-workflow logs --run <run-id> [--follow] [--tail <lines>]

--follow / -f — continuously follow new output. Automatically switches to new retry attempt logs when a retry begins.
--tail <lines> — number of lines to show from the end of the current log (default: 50).

Examples:

# Show the last 50 lines of the current attempt log
agent-workflow logs --run <run-id>

# Follow new output (like tail -f)
agent-workflow logs --run <run-id> --follow

# Show the last 200 lines
agent-workflow logs --run <run-id> --tail 200

`agent-workflow abort`

Terminate an active workflow.

agent-workflow abort --run <run-id> --reason "requirements changed"

Configuration

Create agent-workflow.json in your repository root:

{
  "version": "1",
  "defaultExecutor": "reasonix",
  "maxCycles": 5,
  "timeoutSeconds": 1800,
  "executors": {
    "reasonix": {
      "binary": "reasonix",
      "model": "claude-opus-4"
    },
    "claude": {
      "binary": "claude"
    },
    "agy": {
      "binary": "agy",
      "agent": "code-assistant"
    }
  }
}

Environment Variables

AGENT_WORKFLOW_DIR — Override state root (default: ~/.agent-workflow/workflows)
AGENT_WORKFLOW_META_STDOUT — Emit metadata to stdout instead of stderr (set to 1)

The Agy adapter runs its non-interactive implementation sessions with --dangerously-skip-permissions. This is required because Agy cannot prompt for tool approval in --print mode. The workflow's frozen scope, Git gates, and executor safety prompt remain the authorization boundary. Its internal --print-timeout is set from the workflow timeoutSeconds value so long tasks do not fall back to Agy's five-minute default.

State Machine

executing → awaiting_review → awaiting_host → executing (next cycle)
                           ↘ awaiting_scope_resolution ↗

Any active state → completed | needs_human | blocked | budget_exhausted | aborted

Scope Gates

All file modifications must stay within the approved scope. Out-of-scope changes trigger awaiting_scope_resolution, where Codex inspects each violation and decides whether to remove it or escalate to needs_human.

Convergence Limits

The workflow stops with needs_human when:

The same finding persists across 2+ consecutive cycles
Findings oscillate (disappear then reappear)

Development

npm install
npm run build
npm test
npm run check

License

MIT — see LICENSE and NOTICE for details.