awsl — durable local runtime with resume for Codex and Claude Code Workflows

The local control plane for coding-agent workflows.

Run compatible Claude Code Workflows on Codex without rewriting them. Kill the process. Resume the run.

Codex-verified. Claude-compatible.

The model is the worker. awsl is the runtime.

awsl is the Agent Workflow State Layer: a durable local runtime for trusted coding-agent Workflow JavaScript. Write a workflow once, run it through Codex or the Claude-compatible adapter, and resume it after interruption. awsl owns the runtime pieces that multi-agent scripts usually rebuild: bounded parallelism, shared budgets, durable journals, isolated Git worktrees, versioned events, and redaction.

awsl runs the provider CLIs you already use. It is local, inspectable, and deliberately smaller than a general-purpose agent framework.

Quick start

Install awsl and check the local provider setup:

npm install --global @xhinliang/awsl
awsl --install-skills
awsl doctor

--install-skills installs the awsl Codex Skill in ~/.agents/skills/awsl. It is safe to run again after upgrading awsl.

doctor reports every provider independently and bases overall readiness on the selected provider. An unavailable unused provider does not degrade the selected path. Versions with committed protocol evidence are verified; other strictly branded semantic versions are unverified and may still run.

Run the built-in three-logical-call demo with an 8k output-token gate:

awsl demo --provider codex

demo invokes the selected model provider and creates a normal durable run. The gate stops new calls after recorded output reaches 8k; already active calls may finish above it.

Create a ready-to-run review workflow without writing JavaScript:

awsl init review.js --template code-review
awsl workflow inspect review.js

Select the provider when the run starts:

awsl run review.js \
  --provider codex \
  --args '{"scope":"the authentication module"}' \
  --budget 20000

awsl run review.js \
  --provider claude \
  --args '{"scope":"the authentication module"}' \
  --budget 20000

One provider is pinned for the complete workflow tree. awsl never silently falls back to another provider during a run. The Codex path has real-provider acceptance evidence. The Claude-compatible path has protocol and conformance coverage; authenticated Claude acceptance remains an explicit evidence gap.

Why awsl

Provider CLIs are excellent workers. A workflow that coordinates many calls still needs runtime semantics of its own.

workflow.js ──> awsl runtime ──┬──> Codex CLI
                │              └──> Claude Code
                └── journal · budget · events · worktrees

Read why awsl exists, including when a direct provider CLI or a general-purpose distributed workflow engine is the better choice.

Example workflows

• Browse the five-workflow gallery
• research-panel.js — independent research and synthesis
• parallel-code-review.js — parallel specialist review
• knowledge-compile.js — source-grounded repository knowledge
• incident-investigation.js — evidence-ranked incident assessment
• migration.js — planned migration in an isolated worktree
• worktree-refactor.js — isolated coding-agent worktrees
• resume-after-failure.js — stable labels and durable reuse

The reporting migration case study shows how a real reporting application moved provider-neutral scheduling into awsl while keeping collection, validation, persistence, and delivery in the domain layer.

Requirements and compatibility

• Node.js 22 or newer
• Git for isolation: "worktree"
• At least one Codex CLI or Claude Code executable with a standard semantic version banner

awsl owns and versions the JavaScript Workflow ABI independently from provider executables. This release normalizes structurally compatible workflow files to awsl-workflow@1. Codex CLI 0.145.0 and 0.146.0, and Claude Code 2.1.218, have committed protocol evidence; newer versions are accepted as unverified rather than rejected by a patch-version allowlist.

Read the full awsl-workflow@1 portable workflow ABI proposal.

See the compatibility report for the evidence behind each verified, partial, or unsupported behavior.

From a source checkout:

corepack enable
pnpm install --frozen-lockfile
pnpm run build
pnpm awsl --help

CLI

awsl <workflow>
awsl demo [topic]
awsl init [file] [--template <template>]
awsl run <workflow>
awsl resume <run-id>
awsl runs list
awsl runs show <run-id>
awsl runs pause <run-id>
awsl doctor
awsl config show
awsl workflow inspect <workflow>
awsl --install-skills
awsl help <command>

run accepts:

--provider codex|claude
--args <json>
--args-file <path|->
--cwd <path>
--budget <output-tokens>
--format auto|pretty|jsonl|json

--args, --args-file, and non-empty piped stdin are mutually exclusive. Input JSON is strict, rejects duplicate keys, and is limited to 512 KiB.

resume accepts replacement --args, --args-file, --budget, and --format. The provider, executable profile, working directory, Workflow ABI, and model policy remain pinned. The workflow is reloaded from its stored path; source bytes are not content-pinned, so do not edit a workflow while its run is still resumable. Matching calls reuse the immediately preceding attempt's longest valid result prefix.

Output contracts:

• auto selects pretty for a TTY and jsonl otherwise.
• pretty writes progress to stderr and the final business result to stdout.
• jsonl writes only versioned events to stdout.
• json writes one terminal envelope. In addition to the business result, budget, and aggregate token metrics, completed invocations include a versioned timing summary.

timing is derived from the durable lifecycle events, so awsl runs show <run-id> can report it for runs created by earlier awsl versions too. It contains:

• lifecycle elapsedMs, attempt-active activeMs, time between attempts as idleMs, and the union of live agent intervals as callActiveMs;
• each attempt and call, including queue, execution, retry, and elapsed time;
• per-attempt phase rollups with elapsed and active time, cumulative call time, maximum parallelism, the longest call, and the last finishing call.

Phase elapsed times can overlap when workflows run phases concurrently and cumulative callMs can exceed wall-clock time. Reused calls have elapsed time but no live durationMs.

• SIGINT exits 130 and SIGTERM exits 143 after a durable terminal record.

doctor probes Node, Git, Codex, and Claude versions without invoking a model. Its overall status follows the configured provider, while every provider keeps an independent availability and evidence status.

Workflow contract

The first statement must be a pure literal export const meta = .... meta.name and meta.description are required non-empty strings. Workflow source is limited to 512 KiB and may use top-level await and return. awsl workflow inspect <file> reports the normalized Workflow ABI. The ABI is versioned by awsl rather than by the installed Claude or Codex executable. The normative observable contract is documented in the awsl-workflow@1 proposal.

The workflow global API is:

• args: the strict JSON input.
• agent(prompt, options?): run one provider call.
• parallel(thunks): run branches concurrently and preserve input order.
• pipeline(items, ...stages): process items concurrently while stages for each item remain serial.
• phase(title): change the current display and event phase.
• log(message) and console.*: emit workflow log events.
• workflow(reference, args?): invoke one child workflow.
• budget.total, budget.spent(), and budget.remaining().
• bounded setTimeout and clearTimeout.

Supported agent options are:

{
  label: "stable call label",
  phase: "phase name",
  schema: { type: "object" },
  model: "provider model or configured tier",
  effort: "low" | "medium" | "high" | "xhigh" | "max",
  isolation: "worktree",
  agentType: "registered-agent-name",
}

Non-cancellation failures inside parallel and pipeline become null and emit a log, matching the stable Workflow ABI. A null pipeline value skips the remaining stages for that item. Child workflows inherit the root provider and shared limits; a child cannot recursively start another c