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, VCS baseline gates, scope enforcement, and convergence limits
Supports both Git and SVN working copies with strict validation

Prerequisites

Node.js >= 20
Git repository or SVN working copy
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> [--vcs <git|svn|none>] [--max-cycles <n>] [--new-task]

--vcs - Explicitly specify VCS kind (git, svn, or none). If omitted, auto-detects from the working directory. If neither Git nor SVN is detected, it automatically falls back to none (snapshot mode).
When CODEX_THREAD_ID is available, runs in the same Codex thread and repository share a current task. Each executor is created lazily on first use and its reliable session handle is reused by later plans in that task.
--new-task creates a new task boundary and clears all three lazy executor bindings. Use it only when the conversation has moved to a materially different task.
Claude, Reasonix, and Agy bindings remain separate. Selecting another executor does not switch an active run; it starts or resumes that executor only in a later run after the repository is clean.
Agy sessions without a captured conversation ID are not shared because --continue cannot guarantee which conversation will be selected.
Git and SVN working copies are automatically detected when --vcs is not provided.
SVN working copies must be in a clean, consistent state (no mixed revisions, switched paths, externals, or conflicts).
None (snapshot) mode skips clean checks, capturing the directory state of the working directory and storing it in the run directory.

`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>

If a failed Claude launch recorded a session ID that was never created, explicitly bind a known persisted Claude session from the same repository and frozen plan while retrying:

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

The override is accepted only for Claude runs. The session JSONL must exist under ~/.claude/projects, belong to the run repository, and contain the frozen plan title. Baseline, scope, and review-artifact gates still apply, and the old/new session IDs are appended to the workflow audit log.

For Reasonix runs blocked after a session handle was not captured, retry-execute automatically recovers the persisted session only when its project directory, frozen plan title, and execution time window match the run. The recovery is recorded in the workflow audit log.

`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.
When CODEX_THREAD_ID is set, only one --follow process for a given Run is allowed per Codex thread. A duplicate follower is rejected without affecting the executor; stale locks from dead followers are cleaned automatically. Different threads and manual viewers without CODEX_THREAD_ID remain allowed.
--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"

`agent-workflow extend`

Extend a budget_exhausted run with additional cycles. The run must have ended at budget_exhausted status with a valid session handle and a final fix decision.

agent-workflow extend --run <run-id> --additional-cycles <n>

This allows continuation of the same executor session after reaching the cycle limit, preserving all audit history and convergence checks.

Configuration

Create agent-workflow.json in your repository root:

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

timeoutSeconds is an inactivity timeout, not a total runtime limit. The host resets the timeout whenever the executor emits stdout/stderr progress, so an active task may run longer than the configured window. A continuously silent executor is terminated after the configured number of seconds. Agy receives a 24-hour internal print-mode ceiling while the host inactivity timeout remains the primary stuck-process guard.

defaultVcs - Default VCS kind: "auto" (detect), "git", "svn", or "none". Default is "auto".

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)
CODEX_THREAD_ID — Supplied by Codex. Enables task-level executor session reuse for the current Codex thread and repository. Without it, each workflow run keeps the previous standalone behavior.

Task bindings are stored under the workflow state root, outside the target repository. Before reuse, the host checks the owning Codex thread, repository, task, executor kind, and persisted executor session. A missing or mismatched session blocks reuse instead of silently selecting a recent session. Start with --new-task only when a fresh task is intended.

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 to a 24-hour internal ceiling so active tasks do not fall back to Agy's five-minute default; the workflow inactivity timeout remains the primary guard.

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.

VCS Support

Git

Standard Git repositories are fully supported with baseline HEAD tracking and diff generation.

SVN (Strict Mode)

SVN working copies are supported with strict validation:

Requires: Single consistent revision (no mixed revisions)
Rejects: Switched paths, externals, conflicts, incomplete states, locked files
Baseline: Repository URL, UUID, and working revision
Diff: Tracks modifications, additions (including unversioned), deletions, and property changes
The workflow never runs svn commit, svn switch, or svn update

None (Snapshot Mode)

Used for directories without any version control system.

Trigger: Runs automatically when no Git or SVN repository is found, or when forced using --vcs none (or config defaultVcs: "none").
Clean Checks: Skips standard VCS cleanliness checks.
Baseline: Captures and writes metadata, file paths, size/content hashes, text contents, and symlink targets into baseline-snapshot.json in the workflow run directory.
Diff: Generates clean unified diffs by comparing active file systems with the captured baseline.
Ignores: Automatically honors POSIX relative rules in .gitignore and .agent-workflowignore. Directories like .git and .svn are always ignored. Only files outside the ignore boundaries are checked against scope gates.
Safety constraints: Dynamic executor safety prompts are adapted so that executors do not attempt to run git status or svn status.

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.