Getting Started

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 @plainconceptsplatform/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:

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.

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.

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"}'

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