Loopw is a macOS app for running YAML graphs of agents, executable tools, and triggers. Its sidebar keeps opened workspaces and their run sessions. Runs in different workspaces can continue while another session is viewed. Each session is one persisted run ID; workspaces and run history stay in their folders. The companion CLI provides offline YAML help, validation, and explicit tool fixture checks. The shared Codex/Claude skill helps author YAML; it does not start, watch, or resume runs.
Loopw is licensed under the MIT License. Anyone may open an issue; see CONTRIBUTING.md for the maintainer-only pull request policy.
Install the macOS Loopw app and open a folder containing loopw.yaml, or use New Workspace to create the bundled starter in a selected folder. New Workspace does not overwrite existing files. Edit loopw.yaml, graphs under flows/, components under components/, tool registrations under drivers/, and executables under tools/ with the shared skill or an external editor. The app reads YAML and can refresh after external changes; it does not edit graph files. Invalid YAML appears as a diagnostic while readable saved history remains available.
The app shows graph routes and node configuration before execution. Select a graph, choose a YAML input file, review its actions and access, then choose Start run. Preflight checks input, needed executables, authentication, storage, and the workspace lock before side effects. The graph shows live progress, and selecting a node opens its configuration, activations, attempts, logs, and output. Runs persist under .loopw/runs/<run-id>/ with saved graph snapshots and checkpoints. A saved session shows its original graph even when current YAML changes. The app also provides Pause, Cancel, environment diagnostics, and optional offline HTML report export for a selected run. A run report is an execution snapshot; unexecuted graphs are viewed in the app.
Trigger components (binary 0.3.0+) are graph entries configured with a five-field cron expression and IANA time zone or a polling interval and registered executable operation. Select a trigger graph in the app, review the polling operation and all future run actions, then choose Start Watch. Polling may have external effects. The first successful poll establishes a baseline; later unseen event IDs start distinct durable runs. Pause Watch saves its identity, cursor, and queued events and pauses an active triggered run. Resume Watch is explicit; a paused triggered session must first be reviewed and resumed separately. Stop Watch remains terminal and retains accepted queued events for a later watch. See the complete local trigger example and watch reference.
Resume is explicit for paused, failed, canceled, or interrupted runs with a usable checkpoint. Pause stops in-flight child processes and saves each interrupted activation; it cannot undo effects already made. The app requires a choice for every uncertain external write before more side effects: rerun, which may repeat an effect, or supply a schema-valid accepted output file. Codex and Claude agents continue saved provider conversations when an invocation began; an unavailable conversation stays paused until the person explicitly chooses Start fresh agent session. A configuration failure before provider launch has no conversation to reopen. Inspect the input, logs, and external state first. A higher cumulative execution cap can be selected when needed. Older runs without checkpoints remain inspectable. Nothing resumes automatically.
Install the executables selected by your graph: git and gh for the editable Git/GitHub templates, Python 3 with PyYAML for those templates, and authenticated codex or claude for agents. The app reports missing executables or authentication in preflight and diagnostics; it does not manage credentials. Model selection is explicit in components.
The reduced CLI is available for authoring checks:
loopw --help
loopw --version
loopw help spec
loopw help authoring
cd my-workspace
loopw validate
loopw tool check git git.status --input status.example.yamlvalidate checks configuration without starting agents or tools. tool check invokes one configured executable against the supplied fixture and validates its response. It may cause real local or remote effects; use it only for an explicitly requested fixture check, preferably against disposable repositories or mocked dependencies. --format yaml provides structured output for validate and tool check. CLI exit 0 means success and 2 means usage, configuration, or check failure.
The shared skill contains editable Python templates for seven Git/GitHub operations, with manifests, components, and fixtures. Copy relevant files into a workspace and adapt them; Loopw does not generate tool business logic. The versioned reference defines YAML and tool protocol rules. Compare loopw --version and each YAML api_version with that reference before authoring. The YAML and tool envelope version is ngthluu.github.io/loopw/v1beta1. Earlier namespace identifiers must be updated in workspace, graph, component, driver, and tool response documents. The shared skill provides the same authoring and app operation guidance for Codex and Claude Code.
From binary 0.3.0, init, execute, resume, runs, logs, draw, report, and doctor are no longer public CLI commands. Scripts using them must move workspace and run operations to the macOS app. The YAML format and existing .loopw/ history remain readable. See workflow operation guidance for uncertain-effect resolution.
For local CLI and skill installation, run make install-local or ./tooling/install-local.sh; this builds the current checkout to ~/.local/bin/loopw and links the product skill into Codex and Claude Code. Run it again after Rust changes, and start a fresh host session after installation. Desktop frontend development lives in desktop; make desktop-ui builds the frontend and make build builds the release CLI and macOS app.
Run the repository checks and build targets documented in AGENTS.md and Makefile. Normal tests use temporary local repositories and fake vendor/GitHub executables. Live provider/GitHub smoke runs require an explicit request, provider authentication, and a designated GitHub test repository; they are never part of CI. See the desktop README for frontend architecture and checks.