CLI Reference

loopy-loop is driven by a single command-line tool: init scaffolds a repo, coordinator and worker run the loop, status and events inspect it, and stop and reload control it. Every command operates on the current working directory, so run them from the root of your target repository.

Command aliases

The package installs two entry points that behave identically: loopy and loopy-loop. This reference uses loopy; use whichever reads better in your shell.

loopy status
loopy-loop status   # exactly the same command

loopy init

Scaffolds loopy-loop's files into the current repository. It is idempotent: it creates any missing files, leaves existing files untouched, and always ensures .loopy_loop/sessions/ is in .gitignore. When it finishes, it prints the list of files it created (or reports that the repo is already initialized).

The default template creates only the reserved goal_check workflow in a set named main. inner_outer_eval creates the recommended outer/inner/eval_reviewer/eval_runner set. pm_planner_dispatcher creates planner/dispatcher workflows for child-session orchestration, and also ships the inner_outer_eval child set its dispatcher spawns — a clean init is executable end to end. See Workflows for how to choose.

loopy init --template inner_outer_eval

loopy coordinator

Runs the coordinator server — the process that owns loop state and dispatches work. It loads loopy_loop_config.yaml, runs a startup preflight, resolves the goal, creates (or resumes) a session, and serves exactly two endpoints, /register and /finished. Leave it running while the loop is active.

loopy coordinator --host 127.0.0.1 --port 8080

Reattach to a session whose coordinator was killed:

loopy coordinator --host 127.0.0.1 --port 8080 --resume

Starting a coordinator against a still-running session without --resume is intentionally fatal, so two coordinators never share one state file. See the HTTP Contract for the endpoint payloads.

loopy worker

Runs the single blocking worker that executes assignments through team-harness. It calls /register once for its first task, then loops — running each workflow and reporting via /finished — until the coordinator returns a stop response. A second worker is refused while the recorded worker is verifiably alive.

loopy worker --coordinator http://127.0.0.1:8080

The worker reaches the model layer too, so if your provider needs an API key, export the variable named by team_harness_api_key_env in the worker's shell as well as the coordinator's. See Configuration.

loopy status

Prints the durable session stack: overall status, session id, completed iteration count, current task, stop reason, subtree token usage and duration, and estimated cost when model_prices is configured. While a child runs it appears below the suspended parent. If there is no state yet, the command says so.

loopy status

status: running
session: 20260712_193000_a1b2c3d4e5f6_7a8b9c0d
iteration_count: 11
current_task: inner (iteration 12, session 20260712_193000_a1b2c3d4e5f6_7a8b9c0d, started 2026-07-12T19:41:07Z)
stop_reason: none
subtree_usage: prompt_tokens=12000 completion_tokens=3000 (iterations fully measured: 11, unknown: 0)
subtree_harness_duration_s: 840
last activity: 12s ago
model families rate-limited: none

For the active task it also reports two best-effort health signals:

• last activity — how long ago the running iteration last wrote to its output directory, so you can tell a progressing loop from a wedged one at a glance. Shows unavailable when there is no active task or no recent write.
• model families rate-limited — any agent model families the harness has recorded as rate-limited (with the reset time), read from the harness run log. Shows none when all families are available, or unavailable when the running harness version does not report this.

loopy status --watch clears and re-renders the view every two seconds until interrupted. loopy status --json prints the same information as a machine-readable JSON payload instead of the text layout — use it for scripts and dashboards rather than parsing the text lines.

loopy events

Prints the deepest active session's versioned events.jsonl stream. --follow tails new events and switches streams when a child starts or finishes; --json emits raw JSON lines.

loopy events
loopy events --follow
loopy events --follow --json

loopy stop

Requests a graceful stop by setting stop_requested=true in the latest top-level session state. When no child is active, the worker exits after its next check-in and the coordinator brings the session to a terminal state. It prints stop requested on success, and errors if there is no state to stop.

loopy stop

For how a workflow stops the loop on its own — versus this operator-initiated stop — see Success & Control.

stop targets the latest top-level session. If a child is active, the child does not see the flag; it terminates normally, then the resumed parent honors the request.

--force

loopy stop --force

The cooperative stop above takes effect only at the next assignment boundary, so a long-running iteration keeps going until it finishes. --force additionally reaps the active iteration's tracked agent subprocesses right away, so a hard stop does not leave orphaned agent CLIs running after the coordinator exits. It reuses the same recovery/reaper path the engine uses for crash cleanup, and the session remains resumable afterward. Use plain stop to let the current work finish; use --force when you need the agents killed now.

loopy reload

loopy reload

Applies a fixed workflow prompt or a changed coordinator-operational setting to a running program without restarting it. It records a reload request; at the next task boundary the coordinator re-reads the workflow prompts and its reloadable, coordinator-side configuration.

Reload is deliberately narrow. It refreshes workflow prompts and coordinator-operational config (for example recovery and failure-cap settings). It does not touch anything frozen per session — the goal, completion/stop criteria, max_turns, the harness provider/model/families, or the workflow contracts and rosters — because a session's model and policy are intentionally immutable for its whole lifetime. To change any of those, stop and start a fresh program.

It prints a confirmation on success, reports No loopy-loop state found. when nothing is running, and asks you to retry if the coordinator state is momentarily locked mid-request.

Where to go next

• Getting Started — these commands in a full first-run walkthrough.
• Configuration — what coordinator reads at startup.
• Troubleshooting — resolving preflight, resume, and API-key errors.