loop-task

loop-task

Loop engineering for your terminal. Run any command on a cadence.

loop-task is a cross-platform CLI that runs shell commands at human-readable intervals. Create loops in the background, manage them from an interactive TUI board, or run them in the foreground. It is the heartbeat primitive for loop engineering: instead of running a task by hand every time, you schedule it once and let it run.

Loop engineering

Loop engineering is designing systems that run work on a cadence instead of triggering each run yourself. A loop is a recurring goal: you define a purpose, give it an interval, and let it iterate. It applies to ordinary engineering work just as much as to AI agents: health checks, sync jobs, test watches, data pulls, deploy polls, and report generation are all loops.

loop-task is that heartbeat as a tiny local primitive. Some examples:

# Run the test suite every 30 minutes
loop-task new 30m -- npm test

# Poll a deploy every 10 seconds until you stop it
loop-task new 10s -- curl -sf https://example.com/health

# Re-sync a data export once an hour, scoped to a project
loop-task new 1h --project etl -- ./scripts/sync.sh

# Have a coding agent chip away at a backlog every 30 minutes
loop-task new 30m -- opencode run "find missing translations and translate them, 3 max"

No cron files to maintain and no daemon to babysit: loops persist across reboots, run in the background, and you watch them from a terminal board. The idea is described well in Addy Osmani's Loop Engineering, where scheduled automations are the first of the five pieces of a working loop.

Stay in control. A loop running unattended is also a loop failing unattended. Use --max-runs, watch the run history on the board, and review what each loop produces. The leverage moves to the loop; the responsibility stays with you.

Quick start

npm install -g loop-task
loop-task                          # open the board (requires Bun)
loop-task start                    # start the daemon, restore persisted loops
loop-task new 30m -- npm test      # create a background loop
loop-task run --now 10s -- echo hi # run a loop in the foreground

Or run it directly:

npx loop-task
npx loop-task new 30m -- npm test

Requirements

• Node.js >= 20 - required for all commands
• Bun >= 1.2 - required for the interactive board only

Install Bun:

npm install -g bun

start, new, and run work with Node alone. The board auto-delegates to Bun when needed.

Concepts

Loops

A loop is a schedule - it defines when something runs. Loops trigger tasks.

Field	Description
Interval	How often to run (30s, 5m, 1h, 1d, 1w)
Task	Inline command or a reference to a previously defined task
Description	Optional label shown in the list; defaults to the task name
Run immediately?	Run once now, then every interval, or wait the first interval
Max runs	Stop after N runs, or leave blank to run forever

Tasks

A task is an executable unit - it defines what runs. Tasks can chain to other tasks on success or failure.

Field	Description
Name	A short label for the task
Command	The full command line
On success	Optional task to run when this one exits with code 0
On failure	Optional task to run when this one exits with a non-zero code

Tasks are reusable - the same task can be referenced by multiple loops or by other tasks' success/failure chains.

Projects

A project is an organizational scope for loops. Every loop belongs to exactly one project. The board shows only loops in the currently selected project.

Field	Description
Name	A short label for the project
Color	One of six colors: white, cyan, orange, green, red, yellow

Key behaviors:

• Default project - always present, cannot be renamed or deleted. New loops are assigned here when no other project is selected.
• Color bullets - each loop in the navigator displays a colored bullet (●) matching its project color.
• Project filter - the board shows only loops belonging to the currently active project. The selection persists across sessions via localStorage.

To use projects from the board:

• Press c to open the Project selector (switch between projects)
• Click Manage Projects in the filter bar (or use the keyboard shortcut) to open the Manage Projects page
• From the Manage Projects page: n creates a new project, e renames the selected project, d deletes it, Esc returns to the board

From the CLI:

• loop-task project list - list all projects
• loop-task project new <name> [--color <color>] - create a project
• loop-task project rename <id|name> <new-name> - rename a project
• loop-task project color <id|name> <color> - change a project's color
• loop-task project delete <id|name> - delete a project (loops move to Default)
• loop-task new <interval> --project <name> -- <command> - create a loop assigned to a project

Colors can be a name (white, cyan, green, yellow, orange, pink) or a #rrggbb hex value.

Commands

Command	Description
loop-task	Open the interactive board (requires Bun)
loop-task start	Start the background daemon, restore persisted loops
loop-task new <interval> -- <command>	Create a background loop (creates an inline task)
loop-task new <interval> --project <name> -- <command>	Create a loop assigned to a project
loop-task run <interval> -- <command>	Run a loop in the foreground
loop-task project list	List all projects
loop-task project new <name> [--color <color>]	Create a project
loop-task project rename <id|name> <new-name>	Rename a project
loop-task project color <id|name> <color>	Change project color
loop-task project delete <id|name>	Delete a project (loops move to Default)

Options (for new and run)

Option	Description
--now	Run immediately before waiting
--max-runs <n>	Stop after N executions
--cwd <dir>	Working directory for the command
--verbose	Show execution details
-h, --help	Display help
-V, --version	Display version

Examples

# Run tests every 30 minutes
loop-task new 30m -- npm test

# Run immediately, then every hour
loop-task new --now 1h -- npm test

# Run up to 5 times, then stop
loop-task run --max-runs 5 5m -- npm test

# Agent workflow - schedule an AI task every 30 minutes
loop-task new 30m --now -- opencode run "search missing translations and translate them, 3 maximum" --model "opencode/big-pickle"
# Run in a specific directory
loop-task new 30m --cwd ./packages/api -- npm test

# Verbose mode
loop-task run --verbose 30m -- npm test

When the command has its own flags, use -- to stop argument parsing:

loop-task new 30m -- node -e "console.log('hello')"

The board

The board is the primary way to manage loops and tasks. It shows all loops, their status, run history, and logs in a single terminal interface.

Board controls

↑/↓, j/k    move selection
Enter       edit selected loop
e           edit loop
d/del       delete loop
p           pause (when waiting) / play (when idle/paused)
s           stop loop (resets schedule)
n           create a new loop
t           create a new task
o           cycle sort mode (order by)
←/→         switch between panels
/           search loops
h           toggle help
esc         quit

Destructive actions (pause, force run, delete) prompt a confirmation before executing.

Pause vs Stop

• Pause (p) - temporarily halts the loop. Resuming continues the original schedule (e.g., a loop that runs every 6h at :00 paused at 12:00 and resumed at 14:00 will still fire at 16:00).
• Stop (s) - halts the loop and clears the schedule. Playing starts a fresh interval from now (e.g., the same loop stopped at 12:00 and played at 14:00 will fire at 20:00).

How it works

loop-task (board) ──IPC──► daemon ──► loop 1 ──► task (command)
                           ├──► loop 2 ──► task ──► on-success task
                           └──► loop 3 ──► task ──► on-failure task

• The daemon is a background process that manages all loops and tasks. It starts automatically when you run loop-task start or any command that needs it.
• The board is a terminal UI that connects to the daemon via IPC.
• Loops define schedules and reference tasks. Tasks define commands and optional success/failure chains.
• Loops and tasks persist to disk - they survive daemon restarts and system reboots. When the daemon starts, it restores all loops and accounts for elapsed time.

Lifecycle

• loop-task start or loop-task new ... spawns the daemon if not running
• The daemon creates a loop and a task, and persists their state to disk
• loop-task opens the board for interactive management
• Closing the board or terminal does not stop loops - the daemon keeps running
• After a reboot, loop-task start restores all persisted loops with correct timing

Supported intervals

Format	Description
10s	10 seconds
5m	5 minutes
1h	1 hour
1d	1 day
1w	1 week

Behavior

• No overlapping - waits for the command to finish before starting the next interval
• Resilient - continues looping even if a command exits with a non-zero code
• Persistent - loop and task state is saved after every run; survives restarts
• Graceful shutdown - background loops are daemon-managed; foreground loops finish the current execution on Ctrl+C

Development

Requires Bun >= 1.2 for package management and the board, and Node.js >= 20 for the CLI and daemon.

bun install
npm run build

Run locally:

bun run dev                                    # board
node dist/entry.js new --now 30m -- npm test   # background loop
node dist/entry.js run --now --max-runs 1 10s -- echo hello  # foreground

Quality gates:

bun run typecheck
bun run lint
bun run test
npm run build

License

MIT