Codex or Claude 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

Host Skill Installation

The agent-workflow-host skill provides the instructions for Codex or Claude to act as the workflow host.

Codex

Codex uses ~/.codex/skills/agent-workflow-host.

mkdir -p ~/.codex/skills/agent-workflow-host
cp node_modules/agent-workflow/skills/agent-workflow-host/SKILL.md ~/.codex/skills/agent-workflow-host/

Claude Code

Claude uses ~/.claude/skills/agent-workflow-host.

mkdir -p ~/.claude/skills/agent-workflow-host
cp node_modules/agent-workflow/skills/agent-workflow-host/SKILL.md ~/.claude/skills/agent-workflow-host/

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> --reviewer <codex|claude>

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

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

Commands

`agent-workflow start`

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

agent-workflow start --plan <plan.json|-> --executor <reasonix|claude|agy> [--reviewer <codex|claude>] [--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 host review bundle after executor completion. Checks HEAD stability and scope compliance.

agent-workflow review --run <run-id> --reviewer <codex|claude>

Once the run is at or past the guidance threshold — the executor cycle about to start is >= 3 (i.e. reviewing cycle 2, so the next fix cycle would be the third round) — the bundle sets detailedGuidanceRequested: true and includes a reviewerInstructions string. This asks the host, if it decides fix, to return a concrete step-by-step implementation plan so the executor can converge quickly.

`agent-workflow decide`

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

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

A fix decision may include an optional implementationGuidance string (up to 20000 characters). When present, it is injected verbatim into the executor's fix prompt under a ## Detailed Implementation Guidance section, and the frozen plan's planMarkdown and acceptance criteria are re-sent alongside it so the executor has full context. This is the channel the host uses to answer the bundle's detailedGuidanceRequested signal, and it flows through the normal fix, retry-execute, and extend paths.

`agent-workflow retry-review`

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

agent-workflow retry-review --run <run-id> --reviewer <codex|claude>

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

Start a local web console to monitor agent executions, runs, cycles, and logs in real-time, and to manage host-wide executor model overrides.

agent-workflow web [--port <n>]

--port <n> — specify a custom port to listen on (default: 4317).
Security & Scope — The server binds exclusively to the loopback interface (127.0.0.1) for local-only access. It refuses any external or remote listener configurations. Since executor logs can contain sensitive code, configuration details, or tokens/credentials, binding to 127.0.0.1 ensures that the console remains local. Mutation endpoints require same-origin localhost requests, JSON content type, bounded bodies, and validated model values. Credentials are never returned to the browser.
Workflow monitoring remains read-only — The console provides no endpoints to start, stop, decide, or otherwise control workflow runs. It parses and displays execution progress, cycles, timeline, and stdout/stderr output. It cannot recover or display private reasoning tokens/processes of underlying models that are not output to the console.
Writable global model settings — The Chinese “全局执行器模型配置” view can independently set Claude, Agy, and Reasonix models. Discovery uses the current CLI environment: Claude via Anthropic /v1/models (with configured-default fallback), Agy via agy models, and Reasonix via reasonix doctor --json provider/model entries. Reasonix candidates use the CLI-compatible provider/model form, with provider-only fallback when no concrete model is listed. CLI discovery allows up to 15 seconds for executor startup; HTTP model discovery remains bounded separately. Discovery failures are isolated per executor, and manual entry always remains available. Saving atomically updates only executors.<kind>.model in ~/.agent-workflow/config.json, preserves unrelated fields, and clears an override when the value is emptied. Active executors are not interrupted; saved models take effect on later cycles, scope remediation, extensions, and executor retries through the existing reload path. Project configuration continues to override global values.
Interaction with logs --follow — The web server directly reads the persisted run files without taking any logs follow locks or interfering with the main executor loop, allowing you to use both the CLI logs --follow and the web console concurrently.

`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, and optionally create ~/.agent-workflow/config.json for host-wide defaults. Settings are merged per field with the following precedence:

CLI flags (--executor, --vcs, --max-cycles)
agent-workflow.json in the project root
~/.agent-workflow/config.json
Built-in defaults

{
  "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".
model - Executor model identifier (accepted as any non-empty string). When set, it is passed to Claude, Agy, and Reasonix. The effective model is reloaded from the latest config before each later cycle, scope remediation, cycle extension, and executor retry, so mid-run model changes take effect without starting a new run. Binary path, agent, profile, budget, timeout, and other executor settings are locked at run start.

Configuration files are forbidden from storing secrets (apiKey, token, secret, password, credential, etc.). If the latest config is invalid or the reloaded model is empty, the run enters a blocked state before launching the executor. After correcting the config, the same run can continue with agent-workflow retry-execute --run <run-id>.

The path used to load agent-workflow.json is persisted with the run so later model reloads use the same config source for Git, SVN, and snapshot-mode repositories.

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 the host 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.