Runglet

Internal alpha: PyPI distribution is public for installation convenience. The GitHub repository, Releases, Issues, CI, and hosted documentation are intentionally private and their links require invited alpha access.

Runglet lets you develop PLC control software with coding agents instead of drawing ladder diagrams by hand.

It is a typed, deterministic source language and offline toolchain. You describe control intent and scan-level tests as text; Runglet gives people and agents structured diagnostics, versioned authoring context, exact-scan scenarios, and deterministic builds. A checked program lowers to canonical Relay IR and, for a supported target subset, vendor artifacts such as ladder logic.

The aim is not to hide PLC semantics. It is to make scan behavior, state ownership, interlocks, numeric policy, and output arbitration explicit enough for an agent to write, inspect, test, repair, and review without using a vendor editor as the primary programming environment.

You still need to understand the controlled process and the PLC execution model. You should not have to learn a vendor's ladder drawing workflow just to express and test that logic.

Runglet is alpha software. The compiler, reference runtime, formatter, language server, VS Code extension, and offline project workflow are usable today. Target deployment is still evidence-gated and is not production-ready. The current package is 0.5.3, a compiler conformance patch. It repairs numeric comparisons, private declaration identity, and offline instruction selection under the existing language contract. Release details. The portable language specification is independently versioned and frozen at 0.22.0.

Why Runglet

• Ladder is a target, not the authoring interface. Application logic is written and tested as ordinary text. Supported backends take responsibility for the mechanical target representation.
• Scan behavior is part of the program. Snapshot-atomic state, following-scan commits, timer behavior, and output ownership are checked instead of inferred from rung order.
• Tests live beside the logic. Embedded scenarios run against an exact-scan reference runtime without a PLC or vendor IDE.
• Builds are reviewable. Source, Relay IR, target plans, profiles, and generated artifacts carry deterministic identities and stable semantic IDs.
• Agents get a real development interface. Generated workflow files, bounded context packs, stable diagnostics, JSON inspection, checked examples, and fail-closed target discovery keep an agent tied to the installed compiler rather than its memory of the language.

Agentic development is a compiler feature

runglet init creates more than a sample program. It creates an agent-ready workspace with task guidance, a machine-readable capability manifest, thin tool skills, agent entry points, checked source, and a scaffold identity. From there, the supported loop is explicit:

requirements brief
  -> discover the installed language, libraries, and target limits
  -> author Runglet source and scenarios
  -> repair stable compiler diagnostics
  -> format, check, and run exact-scan tests
  -> inspect deterministic builds and target plans
  -> hand reviewable evidence to the target-specific engineering step

The agent does not need to read Runglet's Python implementation or guess syntax from a prompt. These commands expose the contract it needs:

runglet authoring-context --profile core --format markdown
runglet inspect --package runglet.std.control --json
runglet check runglet.toml --json
runglet suite runglet.toml
runglet target inspect fatek-fbs --json

This does not remove the need to understand the controlled process, electrical design, failure behavior, or commissioning boundary. It removes hand-authored ladder from the normal implementation loop. Read the agentic authoring guide for the workspace contract and a practical task handoff.

A one-minute example

Install the command-line application with pipx:

pipx install runglet==0.5.3
runglet init demo --name demo
cd demo
runglet check runglet.toml
runglet suite runglet.toml

The default starter is a project ready for imports and additional files. It contains ordinary control logic and two executable scenarios:

RULE run_permission:
  ID "RULE-RUN-PERMISSION-001"
  DRIVE permitted
  WHEN:
    start_requested
  END
END

OUTPUT_LOGIC demo_command:
  ID "LOGIC-DEMO-COMMAND-001"
  DEFAULT FALSE
  TURN_ON WHEN:
    permitted
  END
END

The suite result is short enough to read in a terminal and detailed enough to retain as JSON when needed:

SCENARIO SCENARIO-REQUESTED-COMMAND-001: PASS scans=1
SCENARIO SCENARIO-IDLE-COMMAND-001: PASS scans=1
SUMMARY passed=2 failed=0 total=2

Start with the getting-started guide for installation choices, VS Code setup, and the full authoring loop.

What works today

The current status and exact exclusions are maintained in Language readiness, not inferred from release notes or screenshots.

Installation

Runglet requires Python 3.12 or later.

pipx install runglet==0.5.3

To install a downloaded or locally retained 0.5.3 wheel into an existing environment:

python -m pip install ./runglet-0.5.3-py3-none-any.whl

For invited alpha testers, tagged GitHub Releases also provide:

• the Python wheel and source archive;
• a standalone Windows ZIP containing runglet.exe, runglet-lsp.exe, and their private runtime;
• the matching VS Code VSIX; and
• SHA256SUMS for the published assets.

The Windows executables launch directly and do not use PowerShell. See Windows installation.

For invited contributors with repository access, source development starts with:

git clone https://github.com/vedit/Runglet.git
cd Runglet
uv sync --extra dev --locked

How it fits together

Runglet source
    │
    ├── analysis, diagnostics, formatting, LSP
    │
    └── canonical Relay IR
          ├── reference scenarios, traces, properties
          ├── portable resource reports
          └── target preflight, planning, and review bundles

Relay IR is the portable semantic boundary. A backend must preserve the selected execution model, use a named emulation strategy, or reject the program. Vendor syntax acceptance alone is not treated as proof of equivalent behavior.

Physical addresses are not written into .rung source. Acquisition and output publication live in separate, versioned binding manifests so logical behavior can be reviewed and tested before a physical contract exists.

Project workflow

Use a project layout when the program will have multiple files or standard-library dependencies:

runglet init plant-control --name plant_control --layout project
cd plant-control
runglet authoring-context --profile core --format markdown
runglet check runglet.toml
runglet suite runglet.toml
runglet build runglet.toml --output build/main

If a generated loose starter later needs imports or packages, promote it without merging a second scaffold:

runglet init . --promote --dry-run --json
runglet init . --promote

Useful discovery commands include:

runglet help --all
runglet inspect --package runglet.std.control --json
runglet inspect --package runglet.std.control --example
runglet target list --json
runglet target inspect fatek-fbs --json

The CLI and project guide covers locks, offline packages, target planning, and deterministic output ownership.

Boundaries

Runglet is not a certified or qualified safety development tool. A passing check, scenario suite, vendor import, simulator run, or isolated bench observation establishes only the claim attached to that exact gate and artifact.

Authoring and compilation do not authorize contact with WinProLadder, a PLC, HIL, or production equipment. Credited protection must remain independent unless a separate safety lifecycle explicitly establishes otherwise.

Read Readiness and safety before using generated target logic beyond offline review.

Documentation

The hosted links below currently require invited alpha access. The installed package remains self-describing through runglet help --all, runglet authoring-context, runglet inspect --package, and runglet target inspect.

• Getting started
• Agentic authoring
• Language tour
• VS Code
• Scenarios and tracing
• Standard library
• Compiler and Relay IR
• Target support
• Language reference

Contributing and license

Invited contributors can see CONTRIBUTING.md for the locked development workflow and review expectations. Please also read the code of conduct and use the security policy for private vulnerability reports.

Runglet is licensed under the Mozilla Public License 2.0. User-authored Runglet programs and compiler-generated artifacts are not relicensed merely because Runglet processes them. The precise boundary is described in LICENSING.md.