# WOML

> WOML is an open-source, HTML-inspired markup language and self-hosted runtime for building durable workflow applications with embedded JavaScript.

WOML (Workflow Orchestration Markup Language) is an open-source, executable format for durable workflow applications, released under the Apache License 2.0. It lets developers describe workflow structure using HTML-inspired markup, embed real JavaScript logic inline, and run the result through a cross-platform, Rust-powered runtime—all from a single `.woml` file. The project is maintained by Mohamed Ali Ben Othmen and is available on GitHub.

## What It Is

WOML occupies the space between visual no-code builders and traditional orchestration frameworks. It is three things working together: a **language** for expressing triggers, steps, decisions, parallel work, loops, approvals, and runtime policies; a **durable engine** that supervises retries, state, events, workflow calls, recovery, and execution history; and an **operational runtime** for running, inspecting, cancelling, backing up, and managing automations from the command line. A `.woml` file is simultaneously the program, the architecture diagram, the execution policy, and the human-readable documentation for an automation.

## How the Language Works

WOML files use semantic XML-like tags that read top-to-bottom, mirroring the actual execution order:

- **`<triggers>`** — webhook, schedule, interval, internal event, Slack, Telegram, Discord, WhatsApp
- **`<steps>`** — sequential steps with embedded `<script>` blocks using `context.payload`, `context.steps`, `services`, and `secrets`
- **`<parallel>`** — concurrent step groups with bounded concurrency and configurable error handling
- **`<choose>` / `<switch>`** — conditional branching with explicit `<when>` and `<otherwise>` paths
- **`<fork>`** — independent multi-step branches with explicit joins
- **`<approval>`** — durable human-in-the-loop pauses
- **`<imports>`** — explicit local JavaScript or TypeScript module imports exposed as `services.*`

Runtime policies (concurrency, rate limits, queues, timeouts, retries, lifecycle hooks) live as attributes on the workflow element, making the execution contract part of the readable source.

## Self-Hosted Deployment Model

WOML is fully self-hosted. The same workflow file runs on a developer's machine, a server, a container, or any infrastructure without per-step platform billing. Installation is via the `woml-cli` npm package, which automatically selects the appropriate native Rust engine for macOS, Linux (glibc 2.31+), or Windows. Bun 1.3.14 or later is required as the JavaScript runtime. Common CLI operations include `woml check` for validation, `woml run` for foreground execution, `woml inspect` for the colored runtime inspector, and `woml backup` for state store snapshots.

## AI-Friendly Architecture

The README describes WOML as designed for AI agent collaboration: tags constrain workflow structure, JavaScript provides familiar implementation power, `woml check` catches invalid output, and Git exposes exactly what an agent changed. A downloadable **WOML Skill** package teaches coding agents (Claude Code, Codex, and others) the language structure, runtime bindings, control-flow patterns, services, and validation workflow needed to generate valid `.woml` files. WOML can also orchestrate AI systems themselves—LLM or tool calls run as supervised steps, specialist agents become child workflows, and human approval guards sensitive actions.

## VS Code Integration

The repository includes a dedicated VS Code extension (`woml-vscode/`) that provides HTML-style markup highlighting for `.woml` files, embedded JavaScript syntax coloring, highlighted runtime bindings (`context`, `services`), reference-expression highlighting, snippets, and a dedicated file icon. The extension follows the user's existing VS Code theme.

## Update: v1.0.10

The latest release is **v1.0.10**, published on 2026-08-31. The repository was created in July 2025 and has seen active development, with the last push on the same date as the latest release. The project lists 128 stars and 11 forks on GitHub as of the last update. The GitHub topics include `workflow-orchestration`, `self-hosted`, `ai-agents`, `rust`, `typescript`, and `bunjs`, reflecting the project's technical direction toward durable, developer-owned automation infrastructure.

## Features
- HTML-inspired markup language for workflow definition
- Embedded JavaScript logic in <script> blocks
- Durable execution engine with event-sourced history
- Webhook, schedule, interval, Slack, Telegram, Discord, WhatsApp triggers
- Sequential, parallel, fork, choose, and switch control flow
- Human-in-the-loop approval steps with durable waiting
- Local TypeScript/JavaScript module imports as services
- Managed HTTP, SQLite, PostgreSQL, storage, cache, state, and event services
- Retries with configurable backoff and idempotency
- Concurrency, rate limiting, queues, and timeout policies
- Workflow composition: call, start, and event-driven child workflows
- Cross-platform Rust-powered native engine (macOS, Linux, Windows)
- CLI: check, run, inspect, list, cancel, backup, prune, secrets
- VS Code extension with syntax highlighting and snippets
- AI agent skill for generating valid WOML files
- Self-hosted with no per-step platform billing
- Version-controlled .woml files with meaningful diffs

## Integrations
Slack, Telegram, Discord, WhatsApp, PostgreSQL, SQLite, Google Maps (via local module), HTTP APIs, Webhooks, Claude Code, Codex, Bun, npm, pnpm, VS Code

## Platforms
WINDOWS, MACOS, LINUX, API, VSC_EXTENSION, CLI

## Pricing
Open Source

## Version
v1.0.10

## Links
- Website: https://woml.org
- Documentation: https://woml.org/docs/
- Repository: https://github.com/dali-benothmen/woml
- EveryDev.ai: https://www.everydev.ai/tools/woml