loopkeel 0.1.0

A resilient CLI orchestrator for agentic work loops
loopkeel-0.1.0 is not a library.

loopkeel

loopkeel is a small Rust orchestration CLI for agentic work cycles: plan, execute, validate, and repeat. It is designed to be called from Claude Code, Codex, or Cursor hooks and tasks. Cursor's native /loop remains untouched; this binary is an external companion.

Install and build

Prebuilt release archives are published for Linux x86_64, macOS Intel, macOS Apple Silicon, and Windows x86_64 from hebertcisco/loopkeel.

Linux

Using curl:

curl -fL "https://github.com/hebertcisco/loopkeel/releases/latest/download/loop-x86_64-unknown-linux-gnu.tar.gz" -o /tmp/loop.tar.gz
tar -xzf /tmp/loop.tar.gz -C /tmp
sudo install -m 755 /tmp/loop /usr/local/bin/loop

Using wget:

wget -O /tmp/loop.tar.gz "https://github.com/hebertcisco/loopkeel/releases/latest/download/loop-x86_64-unknown-linux-gnu.tar.gz"
tar -xzf /tmp/loop.tar.gz -C /tmp
sudo install -m 755 /tmp/loop /usr/local/bin/loop

macOS

Use aarch64-apple-darwin on Apple Silicon and x86_64-apple-darwin on Intel Macs.

Using curl:

LOOP_TARGET="aarch64-apple-darwin" # or x86_64-apple-darwin
curl -fL "https://github.com/hebertcisco/loopkeel/releases/latest/download/loop-${LOOP_TARGET}.tar.gz" -o /tmp/loop.tar.gz
tar -xzf /tmp/loop.tar.gz -C /tmp
sudo install -m 755 /tmp/loop /usr/local/bin/loop

Using wget:

LOOP_TARGET="aarch64-apple-darwin" # or x86_64-apple-darwin
wget -O /tmp/loop.tar.gz "https://github.com/hebertcisco/loopkeel/releases/latest/download/loop-${LOOP_TARGET}.tar.gz"
tar -xzf /tmp/loop.tar.gz -C /tmp
sudo install -m 755 /tmp/loop /usr/local/bin/loop

Windows

In PowerShell, use curl.exe or wget.exe so the commands refer to the native download tools rather than PowerShell aliases:

$repo = "hebertcisco/loopkeel"
$url = "https://github.com/$repo/releases/latest/download/loop-x86_64-pc-windows-msvc.zip"
curl.exe -fL $url -o "$env:TEMP\loop.zip"
Expand-Archive -Force "$env:TEMP\loop.zip" "$env:TEMP\loop"
New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\Programs\loop" | Out-Null
Copy-Item -Force "$env:TEMP\loop\loop.exe" "$env:LOCALAPPDATA\Programs\loop\loop.exe"

The equivalent wget.exe download is:

wget.exe -O "$env:TEMP\loop.zip" "https://github.com/hebertcisco/loopkeel/releases/latest/download/loop-x86_64-pc-windows-msvc.zip"

Add %LOCALAPPDATA%\Programs\loop to PATH if it is not already available in your shell.

Cargo

After the crate is published:

cargo install loopkeel

For development from a checkout:

cargo install --path .
# or: cargo build --release

The installed command is loop and the CLI also documents $loop as an alias. In agent slash-command/task configuration, invoke the external binary as /loop or $loop according to that tool's convention.

Usage

loop start --goal "Implement and validate the feature" --max-iterations 8
loop start --goal "Fix the bug" --success-command "cargo test" --retries 4
loop step
loop status
loop pause
loop resume
loop stop

The goal may also be loaded from a plan file with --plan path/to/plan.md. Configuration is read from .loop.toml; CLI values override it. Durable files are .loop/state.json, .loop/events.jsonl, and .loop/control. A checkpoint is atomically replaced after every iteration, so Ctrl+C leaves a resumable state.

--agent claude|codex|cursor selects the adapter. Use --output json for structured agent ingestion, or --output text for humans. Logging supports RUST_LOG=info and --log-format json.

Install the agent skill

The repository includes one portable SKILL.md that works with both Claude Code and Codex. Install it into the current project with:

loop skill install --target both

This creates .claude/skills/loop-orchestrator/SKILL.md and .codex/skills/loop-orchestrator/SKILL.md. To install for the current user instead, use --scope user; to replace an existing copy, add --force:

loop skill install --target codex --scope user --force
loop skill path --target claude

The skill teaches the host agent how to start, inspect, pause, resume, and validate a loop. It does not replace Claude Code commands or Cursor's native /loop; it configures an external companion workflow.

Agent integration examples

Claude Code or Codex can call loop start --goal "$TASK" --agent claude from a hook/task and inspect loop status between actions. A completion signal can be sent with printf complete > .loop/control; loop stop is the intentional stop command.

For Cursor, configure an external task or hook to run loop start ... --agent cursor; this does not register or replace Cursor's built-in /loop. Cursor can consume loop status --output json or the JSON event stream.

Stop criteria and resilience

Loops stop at max_iterations, after success_command passes, after an explicit complete control command, or on stop/interrupt. Transient validation failures use exponential backoff (backoff_ms * 2^attempt) up to retries; a final failure is reported as a typed error. The async engine uses tokio::select! for Ctrl+C, control-file commands, and iteration timers. Events are appended to JSONL and are not retained as an in-memory history.

Development

cargo test
cargo run -- status

To simulate resume, start a loop, press Ctrl+C, then run loop status; the checkpoint remains on disk with the last completed iteration. Start again with the same project directory to continue with a new run. Generated changes are not committed or published automatically.