loop-task: Run anything on a cadence

What is loop-task?

loop-task is a CLI tool for loop engineering - running any shell command on a cadence in the background. You tell it to run something every 30 minutes, every hour, every day - and it does, quietly, until you tell it to stop. A background daemon manages all your loops, and you control them from an interactive terminal board. No cron files, no systemd services, no config syntax to learn.

Requirements

Node.js 20+ - earlier versions are not supported.
macOS, Linux, or Windows - fully cross-platform.

Installation

Install globally via npm:

npm install -g loop-task

That's it. The loop-task binary is now on your PATH.

Verify it's installed:

loop-task --version

Your first loop

Let's create a loop that runs your test suite every 30 minutes.

loop-task new 30m -- npm test

That's the whole command. Break it down:

Part	Meaning
`loop-task new`	Create a new loop
`30m`	Run every 30 minutes
`--`	Separator: everything after this is the command to run
`npm test`	The command itself

What just happened?

The daemon started automatically in the background. Your loop is now running - it will execute npm test every 30 minutes, capture the output, and log it. You can close the terminal, come back later, and it's still running.

That's it - you're looping

The daemon keeps running after you close your terminal. Loops survive reboots. State is persisted to disk as JSON - no database, no config files.

Check status

To see all your loops:

loop-task status

You'll see output like this:

┌──────────────────────────────────────────────────────────┐
│ ID        │ Command    │ Interval │ Status  │ Next Run   │
├──────────────────────────────────────────────────────────┤
│ abc123    │ npm test   │ 30m      │ running │ in 24m     │
└──────────────────────────────────────────────────────────┘

Note the ID - you'll need it to control this loop.

Stop it

loop-task stop abc123

The loop stops. The daemon keeps running in the background, ready for your next command.

Opening the board

Run loop-task with no arguments:

loop-task

This opens the interactive TUI board - a full terminal interface for managing everything. You'll see:

A header with daemon status and loop count
A left panel listing all your loops
A right panel showing details for the selected loop
A command input at the bottom where you type actions

From the board you can navigate with arrow keys, type commands in the bottom input, inspect run history and logs, edit loop intervals, and switch between Loops, Tasks, and Projects tabs.

Everything available from the board

The TUI board is not a read-only view - it's a full command-first interface. Everything you can do from the CLI, you can do from the board, plus live monitoring, code editing, and chain visualization.

Three ways to do everything

loop-task gives you three ways to control your loops. Use whichever fits your workflow:

Create a loop - three ways

CLI

loop-task new 30m -- npm test

TUI board

loop-task
# Then type: new loop

HTTP API

curl -X POST http://127.0.0.1:8845/api/loops \
  -H "Content-Type: application/json" \
  -d '{"command": "npm test", "intervalHuman": "30m"}'

Why three interfaces?

CLI is fast and scriptable - perfect for CI/CD, shell scripts, and one-shot commands. TUI board is interactive - great for managing loops, monitoring status, and exploring history. HTTP API is for integrations - wire loops into dashboards, webhooks, or remote control systems.

Check status - three ways

# CLI
loop-task status --json

# TUI board
loop-task
# Navigate to any loop to see its detail panel

# HTTP API
curl http://127.0.0.1:8845/api/loops

Stop a loop - three ways

# CLI
loop-task stop abc123

# TUI board - select the loop, press `s` to stop

# HTTP API
curl -X POST http://127.0.0.1:8845/api/loops/abc123/stop

Where to go next

CLI Reference - full list of commands and options
Architecture - how the daemon, CLI, and TUI fit together
Task Chaining - chain multiple tasks together with context passing
Recipe Loops - version-control your loops as YAML files in .loops/recipes/
Agent Workflows - automate AI coding agents on a cadence
OpenTelemetry - built-in tracing for loops, tasks, and agent commands

Getting Started