loopkeel 0.1.0

A resilient CLI orchestrator for agentic work loops
# 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](https://github.com/hebertcisco/loopkeel).

### Linux

Using `curl`:

```sh
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`:

```sh
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`:

```sh
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`:

```sh
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:

```powershell
$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:

```powershell
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:

```sh
cargo install loopkeel
```

For development from a checkout:

```sh
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

```sh
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:

```sh
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`:

```sh
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

```sh
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.