Windlass

A looped agent orchestrator. Windlass runs Claude Code sessions against machine-checkable success criteria and retries until the criteria pass or a stop condition fires.

The core idea: an agent loop is gather, act, verify. The exit condition is named up front, before the agent runs, and it must be machine-checkable. A task succeeds when its HTTP check returns 200, its build command exits 0, or its test suite passes. It never succeeds because the agent says it's done. When a check fails, Windlass feeds the specific failure back into the next attempt's prompt, so each retry starts from evidence instead of a blank slate. Every attempt has a retry cap, a wall-clock timeout, and an audit trail on disk.

What it is

Two entry points over one engine:

• MCP server (dist/index.js): exposes the orchestrator as tools any MCP client can call.

• CLI (windlass): run task files, check status, browse history, scaffold new definitions.

The engine spawns claude --print as a subprocess for each attempt, captures its output, and evaluates the declared criteria against the output and the real world (HTTP endpoints, files, build and test commands).

Related MCP server: mcp-job-queue

MCP tools

The server registers three tools (see src/mcp/server.ts):

Install

Requires Node.js 20+ and the Claude Code CLI (claude) on your PATH.

git clone https://github.com/blakestone-x/windlass.git
cd windlass
npm ci
npm run build

MCP configuration

Add the server to your MCP client config. For Claude Code, in .mcp.json:

{
  "mcpServers": {
    "windlass": {
      "command": "node",
      "args": ["/path/to/windlass/dist/index.js"]
    }
  }
}

CLI quickstart

# Scaffold a task definition
node dist/cli.js define test -o my-test.yaml

# Validate without executing
node dist/cli.js run my-test.yaml --dry-run

# Run it
node dist/cli.js run my-test.yaml --verbose

# Inspect
node dist/cli.js status
node dist/cli.js history -n 10

Task definitions

A task is a YAML or JSON file: a prompt for Claude Code plus the criteria that decide success. Example (adapted from src/tasks/build.yaml):

name: build-project
type: build
prompt: |
  Build the project using the standard build command.
  If there are compilation errors, read each error, fix the source, and rebuild.
model: sonnet
max_retries: 3
timeout_minutes: 10
escalation: stop
retry_backoff: exponential
retry_delay_seconds: 5
success_criteria:
  - type: build_succeeds
    command: "npm run build"

Success criteria

Six check types, defined in src/schema/task.ts and evaluated in src/evaluators/:

Tasks can also declare pre_checks (gate before the agent runs) and post_checks (extra gate after success criteria pass). A post-check failure fails the task.

The loop and its stop conditions

For each task (src/engine/orchestrator.ts):

1. Run pre-checks. If any fail, the task fails without spawning a session.

2. Spawn a Claude Code session with the prompt.

3. Evaluate every success criterion against the session output and the environment.

4. All pass: run post-checks, then mark succeeded.

5. Any fail: log the failure, wait out the backoff delay, and retry with a rebuilt prompt that includes the original task, the specific failed checks, and the tail of the last output.

Stop conditions are wired in, not implied:

• max_retries: the loop runs at most max_retries + 1 attempts, then fails with the configured escalation label (notify, revert, or stop).

• timeout_minutes: a wall-clock budget for the whole task, checked before each attempt and passed down to the session subprocess, which gets SIGTERM then SIGKILL.

• Retry backoff: fixed, linear, or exponential on retry_delay_seconds.

Pipelines

A file with a tasks array runs as a pipeline. Tasks declare depends_on; a topological scheduler (src/engine/scheduler.ts) rejects cycles, runs ready tasks in parallel up to max_concurrent, skips tasks whose dependencies failed, and stops early when fail_fast is set.

Audit log

Every execution, session, and failure analysis is written to SQLite at .windlass/audit.db (override the directory with WINDLASS_DATA_DIR). The status and history CLI commands and the check_task / list_tasks MCP tools read from it, so a crashed process loses no history.

Status

Extracted from a private orchestration stack built to automate engineering work at a national commercial field-service operation. This is its first public release. The core loop, evaluators, pipelines, and audit log are working; the screenshot criterion is a reachability check awaiting a real visual-review backend. Expect the API to move.

License

MIT. See LICENSE.