Loop Extender (loopx)

loopx is a CLI tool that automates repeated execution ("loops") of scripts, primarily designed to wrap agent CLIs. It provides a scriptable loop engine with structured output, control flow between scripts, environment variable management, and a script installation mechanism.

Quick Start

npm install -g loop-extender

# Create a workflow
mkdir -p .loopx/hello
echo 'import { output } from "loopx"; output({ result: "hello", stop: true });' > .loopx/hello/index.ts

# Run it
loopx run hello

Features

• Workflow model — scripts are organized into workflow directories under .loopx/, with index as the default entry point
• Loop engine with goto-based control flow, including cross-workflow transitions (workflow:script)
• Structured output parsing (JSON with result, goto, stop fields)
• Script types: Bash (.sh), JavaScript (.js/.jsx), TypeScript (.ts/.tsx)
• Environment management via loopx env set/remove/list and -e local overrides
• Workflow installation from GitHub repos, git URLs, and tarballs — single- and multi-workflow sources
• Programmatic API with run() (async generator) and runPromise() using workflow:script targets
• Signal handling with proper process group forwarding and grace periods
• CLI delegation for local version pinning via project-root node_modules/.bin/loopx

Running Tests

npm install
npm run build

# Run all tests
npx vitest run

# Run by suite
npx vitest run tests/harness/   # Infrastructure validation
npx vitest run tests/unit/       # Unit tests
npx vitest run tests/e2e/        # End-to-end tests
npx vitest run tests/fuzz/       # Property-based fuzz tests

Test Architecture

| Suite | Files | Purpose | Timeout | |-------|-------|---------|---------| | harness | tests/harness/ | Infrastructure validation | 10s | | unit | tests/unit/ | Parser and type tests | 5s | | e2e | tests/e2e/ | Black-box CLI and API tests | 30s | | signals | tests/e2e/signals.test.ts | Signal handling (serial) | 60s | | fuzz | tests/fuzz/ | Property-based parser tests | 120s | | typecheck | tests/unit/types.test.ts | Compile-time type verification | - |

Requirements

• Node.js >= 20.6 (for module.register())
• Bun >= 1.0 (alternative runtime)
• Platform: POSIX-only (macOS, Linux)

AI Agent Skill

loopx ships with an agent skill that helps AI coding agents create loopx workflows from plain English descriptions.

Install via skills.sh:

npx skills add modularcloud/loop-extender

Install via Claude Code plugin marketplace:

/plugin marketplace add modularcloud/loop-extender
/plugin install loopx@loop-extender

Documentation

See SPEC.md for the full product specification and TEST-SPEC.md for the test specification.