loop-task 1.4.0 → 1.4.1

package/README.md

@@ -1,10 +1,11 @@
 <div align="center">
 
+
 # loop-task
 
-**Run commands on repeat. Manage them from a terminal board.**
+**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.
+`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](#loop-engineering): instead of running a task by hand every time, you schedule it once and let it run.
 
 [![npm version](https://img.shields.io/npm/v/loop-task?style=flat-square&color=black)](https://www.npmjs.com/package/loop-task)
 [![npm downloads](https://img.shields.io/npm/dm/loop-task?style=flat-square&color=black)](https://www.npmjs.com/package/loop-task)
@@ -13,6 +14,34 @@
 
 </div>
 
+## 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:
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/CKGrafico/opencode-task/refs/heads/main/demo.gif" alt="opencode-task demo" width="700" />
+</div>
+
+```bash
+# 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](https://addyosmani.com/blog/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
 
 ```bash
@@ -32,8 +61,8 @@ npx loop-task new 30m -- npm test
 
 ## Requirements
 
-- **Node.js >= 20** — required for all commands
-- **Bun >= 1.2** — required for the interactive board only
+- **Node.js >= 20** - required for all commands
+- **Bun >= 1.2** - required for the interactive board only
 
 Install Bun:
 
@@ -47,7 +76,7 @@ npm install -g bun
 
 ### Loops
 
-A **loop** is a schedule — it defines *when* something runs. Loops trigger **tasks**.
+A **loop** is a schedule - it defines *when* something runs. Loops trigger **tasks**.
 
 | Field | Description |
 | ----- | ----------- |
@@ -59,7 +88,7 @@ A **loop** is a schedule — it defines *when* something runs. Loops trigger **t
 
 ### Tasks
 
-A **task** is an executable unit — it defines *what* runs. Tasks can chain to other tasks on success or failure.
+A **task** is an executable unit - it defines *what* runs. Tasks can chain to other tasks on success or failure.
 
 | Field | Description |
 | ----- | ----------- |
@@ -68,7 +97,7 @@ A **task** is an executable unit — it defines *what* runs. Tasks can chain to
 | **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.
+Tasks are reusable - the same task can be referenced by multiple loops or by other tasks' success/failure chains.
 
 ### Projects
 
@@ -80,9 +109,9 @@ A **project** is an organizational scope for loops. Every loop belongs to exactl
 | **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`.
+- **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)
@@ -90,12 +119,12 @@ To use projects from the board:
 - 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
+- `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.
 
@@ -137,7 +166,7 @@ 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
+# 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
@@ -178,8 +207,8 @@ Destructive actions (pause, force run, delete) prompt a confirmation before exec
 
 ### 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).
+- **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
 
@@ -192,14 +221,14 @@ loop-task (board) ──IPC──► daemon ──► loop 1 ──► task (com
 - 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.
+- 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
 
 1. `loop-task start` or `loop-task new ...` spawns the daemon if not running
 2. The daemon creates a loop and a task, and persists their state to disk
 3. `loop-task` opens the board for interactive management
-4. Closing the board or terminal does **not** stop loops — the daemon keeps running
+4. Closing the board or terminal does **not** stop loops - the daemon keeps running
 5. After a reboot, `loop-task start` restores all persisted loops with correct timing
 
 ## Supported intervals
@@ -214,10 +243,10 @@ loop-task (board) ──IPC──► daemon ──► loop 1 ──► task (com
 
 ## 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
+- **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
 

package/dist/board/components/CreateForm.js

@@ -63,7 +63,7 @@ export function CreateView(props) {
         ? createFields.filter((f) => f !== "runNow")
         : [...createFields];
     const filteredFields = visibleFields.filter((f) => {
-        if (f === "command" || f === "cwd")
+        if (f === "command")
             return isInline;
         if (f === "taskId")
             return !isInline;
@@ -202,12 +202,18 @@ export function CreateView(props) {
                     setError(t("errors.descriptionEmpty"));
                     return;
                 }
+                const cwd = current.cwd.trim();
+                if (cwd && !fs.existsSync(cwd)) {
+                    setError(t("board.cwdMissing", { cwd }));
+                    return;
+                }
                 const built = buildLoopOptions(current.interval.trim(), {
                     now: props.mode === "create" && current.runNow === "y",
                     maxRuns: current.maxRuns.trim() || null,
                     verbose: false,
                     description: current.description.trim(),
                     taskId: current.taskId,
+                    cwd,
                 });
                 built.options.projectId = current.project || "default";
                 const request = props.mode === "edit" && props.editId

package/dist/board/components/TaskBrowser.js

@@ -72,7 +72,7 @@ export function TaskInspector(props) {
         return (_jsx("box", { title: t("board.inspectorTitle"), border: true, style: { backgroundColor: "#0b0b0b" }, children: _jsx("text", { fg: "#9ca3af", children: t("board.inspectorEmpty") }) }));
     }
     const cmd = commandLine(task.command, task.commandArgs);
-    return (_jsxs("box", { title: t("board.inspectorTitle"), border: true, style: { flexDirection: "column", backgroundColor: "#0b0b0b" }, children: [_jsxs("text", { children: [_jsx("strong", { children: t("board.fieldId") }), " ", task.id] }), _jsxs("text", { children: [_jsx("strong", { children: t("board.taskLabelName") }), " ", task.name] }), _jsxs("text", { children: [_jsx("strong", { children: t("board.fieldCommand") }), " ", cmd] }), _jsxs("text", { children: [_jsx("strong", { children: t("board.fieldDir") }), " ", task.cwd || t("board.inherit")] }), _jsxs("text", { children: [_jsx("strong", { children: t("board.taskLabelOnSuccess") }), " ", task.onSuccessTaskId ?? t("board.taskNone")] }), _jsxs("text", { children: [_jsx("strong", { children: t("board.taskLabelOnFailure") }), " ", task.onFailureTaskId ?? t("board.taskNone")] })] }));
+    return (_jsxs("box", { title: t("board.inspectorTitle"), border: true, style: { flexDirection: "column", backgroundColor: "#0b0b0b" }, children: [_jsxs("text", { children: [_jsx("strong", { children: t("board.fieldId") }), " ", task.id] }), _jsxs("text", { children: [_jsx("strong", { children: t("board.taskLabelName") }), " ", task.name] }), _jsxs("text", { children: [_jsx("strong", { children: t("board.fieldCommand") }), " ", cmd] }), _jsxs("text", { children: [_jsx("strong", { children: t("board.taskLabelOnSuccess") }), " ", task.onSuccessTaskId ?? t("board.taskNone")] }), _jsxs("text", { children: [_jsx("strong", { children: t("board.taskLabelOnFailure") }), " ", task.onFailureTaskId ?? t("board.taskNone")] })] }));
 }
 export function TaskActionButtons(props) {
     const { task, focused, selectedAction, selectable = true, onAction } = props;
@@ -80,16 +80,17 @@ export function TaskActionButtons(props) {
         return (_jsx("box", { border: true, borderColor: focused ? "#38bdf8" : undefined, style: { flexDirection: "row", height: 3, flexShrink: 0, backgroundColor: "#0b0b0b", justifyContent: "center", alignItems: "center" }, children: _jsx("text", { fg: "#9ca3af", children: t("board.noActions") }) }));
     }
     const allActions = [
-        { key: "select", label: t("board.taskActionSelect") },
-        { key: "edit", label: t("board.taskActionEdit") },
-        { key: "delete", label: t("board.taskActionDelete") },
+        { key: "select", label: t("board.taskActionSelect"), hotkey: "s" },
+        { key: "edit", label: t("board.taskActionEdit"), hotkey: "e" },
+        { key: "delete", label: t("board.taskActionDelete"), hotkey: "d" },
     ];
     const actions = selectable ? allActions : allActions.filter((a) => a.key !== "select");
-    return (_jsx("box", { border: true, borderColor: focused ? "#38bdf8" : undefined, style: { flexDirection: "row", height: 3, flexShrink: 0, paddingLeft: 1, backgroundColor: "#0b0b0b", alignItems: "center" }, children: actions.map((action, i) => (_jsx(TaskActionButton, { label: action.label, selected: focused && selectedAction === i, onMouseDown: () => onAction(action.key) }, action.key))) }));
+    return (_jsx("box", { border: true, borderColor: focused ? "#38bdf8" : undefined, style: { flexDirection: "row", height: 3, flexShrink: 0, paddingLeft: 1, backgroundColor: "#0b0b0b", alignItems: "center" }, children: actions.map((action, i) => (_jsx(TaskActionButton, { label: action.label, hotkey: action.hotkey, selected: focused && selectedAction === i, onMouseDown: () => onAction(action.key) }, action.key))) }));
 }
 function TaskActionButton(props) {
     const { isHovered, hoverProps } = useHoverState();
     const bg = props.selected ? "#1e3a8a" : isHovered ? HOVER_BG : undefined;
     const fg = props.selected ? "#ffffff" : isHovered ? "#e5e7eb" : "#9ca3af";
-    return (_jsx("box", { onMouseDown: props.onMouseDown, style: { backgroundColor: bg, paddingLeft: 1, paddingRight: 1, marginRight: 1 }, ...hoverProps, children: _jsx("text", { fg: fg, children: _jsx("strong", { children: props.label }) }) }));
+    const keycapFg = props.selected ? "#93c5fd" : "#6b7280";
+    return (_jsxs("box", { onMouseDown: props.onMouseDown, style: { backgroundColor: bg, paddingLeft: 1, paddingRight: 1, marginRight: 1, flexDirection: "row", alignItems: "center" }, ...hoverProps, children: [_jsxs("text", { fg: keycapFg, children: ["[", props.hotkey, "] "] }), _jsx("text", { fg: fg, children: _jsx("strong", { children: props.label }) })] }));
 }

package/dist/board/components/TaskForm.js

@@ -102,7 +102,6 @@ export function TaskForm(props) {
                     name: current.name.trim() || command,
                     command,
                     commandArgs,
-                    cwd: props.editTask.cwd,
                     onSuccessTaskId,
                     onFailureTaskId,
                 });
@@ -115,7 +114,6 @@ export function TaskForm(props) {
                     name: current.name.trim() || command,
                     command,
                     commandArgs,
-                    cwd: "",
                     onSuccessTaskId,
                     onFailureTaskId,
                 });

package/dist/board/hooks/useTaskKeybindings.js

@@ -91,10 +91,18 @@ export function useTaskKeybindings(params) {
                 onTaskAction("edit");
                 return;
             }
+            if (name === "d" && tasks[taskSelectedIndex]) {
+                onTaskAction("delete");
+                return;
+            }
             if (name === "delete" && tasks[taskSelectedIndex]) {
                 onTaskAction("delete");
                 return;
             }
+            if (selectable && name === "s" && tasks[taskSelectedIndex]) {
+                onTaskAction("select");
+                return;
+            }
         }
         if (taskFocusedPanel === "actions") {
             if (name === "up" || name === "k") {
@@ -109,6 +117,14 @@ export function useTaskKeybindings(params) {
                 onTaskAction(taskActions[taskSelectedAction] ?? "select");
                 return;
             }
+            if (name === "d") {
+                onTaskAction("delete");
+                return;
+            }
+            if (selectable && name === "s") {
+                onTaskAction("select");
+                return;
+            }
         }
     });
 }

package/dist/config/constants.js

@@ -21,7 +21,7 @@ export const PROJECT_COLORS = {
     pink: "#f472b6",
 };
 export const PROJECT_COLOR_KEYS = Object.keys(PROJECT_COLORS);
-// Entity theme colors — used for header action buttons and view accents
+// Entity theme colors - used for header action buttons and view accents
 export const ENTITY_COLORS = {
     loop: "#38bdf8", // cyan/blue
     task: "#a78bfa", // purple

package/dist/core/loop-controller.js

@@ -309,7 +309,7 @@ export class LoopController extends EventEmitter {
                 const task = this.options.taskId ? this.taskResolver(this.options.taskId) : null;
                 const command = task?.command ?? this.options.command;
                 const commandArgs = task?.commandArgs ?? this.options.commandArgs;
-                const cwd = task?.cwd ?? this.options.cwd;
+                const cwd = this.options.cwd;
                 const result = await executeCommand(command, commandArgs, cwd, this.logStream, AbortSignal.any([signal, this.runAbortController.signal]), this.runCount);
                 this.runAbortController = null;
                 this.lastExitCode = result.exitCode;
@@ -354,7 +354,7 @@ export class LoopController extends EventEmitter {
                             chainGroupId,
                             chainName: chainTask.name,
                         });
-                        const chainResult = await executeCommand(chainTask.command, chainTask.commandArgs, chainTask.cwd, this.logStream, signal, this.runCount);
+                        const chainResult = await executeCommand(chainTask.command, chainTask.commandArgs, this.options.cwd, this.logStream, signal, this.runCount);
                         const chainLogSize = fs.existsSync(this.logPath) ? fs.statSync(this.logPath).size - chainOffset : 0;
                         const chainRecord = this.runHistory.find((r) => r.chainGroupId === chainGroupId && r.status === "running");
                         if (chainRecord) {

package/dist/daemon/manager.js

@@ -27,7 +27,7 @@ export class LoopManager {
             }
             let taskId = meta.taskId;
             if (!taskId && meta.command) {
-                const task = this.taskManager.createInline(meta.command, meta.commandArgs, meta.cwd ?? "");
+                const task = this.taskManager.createInline(meta.command, meta.commandArgs);
                 taskId = task.id;
                 meta.taskId = taskId;
                 saveLoop(meta);
@@ -245,7 +245,7 @@ export class LoopManager {
             ...runtime,
             command: task?.command ?? options.command,
             commandArgs: task?.commandArgs ?? options.commandArgs,
-            cwd: task?.cwd ?? options.cwd,
+            cwd: options.cwd || "",
             interval: options.interval,
             intervalHuman,
             immediate: options.immediate,

package/dist/daemon/task-manager.js

@@ -43,7 +43,7 @@ export class TaskManager {
         deleteTaskState(id);
         return true;
     }
-    createInline(command, commandArgs, cwd) {
+    createInline(command, commandArgs) {
         const id = crypto.randomUUID().slice(0, 8);
         const name = [command, ...commandArgs].join(" ").slice(0, 40);
         return this.create({
@@ -51,7 +51,6 @@ export class TaskManager {
             name,
             command,
             commandArgs,
-            cwd,
             onSuccessTaskId: null,
             onFailureTaskId: null,
         });

package/dist/i18n/en.json

@@ -62,9 +62,9 @@
     "cli.projectColorSet": "Project \"{name}\" color set to {color}",
     "cli.projectDeleted": "Project \"{name}\" deleted (loops moved to Default)",
     "cli.projectNotFound": "Project not found: {name}",
-    "cli.projectAmbiguous": "Multiple projects named \"{name}\" — use the id instead",
+    "cli.projectAmbiguous": "Multiple projects named \"{name}\" - use the id instead",
     "cli.projectInvalidColor": "Invalid color \"{color}\". Valid names: {valid}, or a #rrggbb hex",
-    "loop.runHeader": "\n[Run #{runNumber} — {timestamp}]\n",
+    "loop.runHeader": "\n[Run #{runNumber} - {timestamp}]\n",
     "loop.exitMarker": "[exit {code} · {duration}]\n",
     "loop.cwdMissingLog": "[error] working directory does not exist: {cwd}\n",
     "loop.cwdMissing": "Working directory does not exist: {cwd}",
@@ -100,8 +100,8 @@
     "errors.resumeFailed": "resume failed",
     "errors.forceRunFailed": "force run failed",
     "errors.deleteFailed": "delete failed",
-    "errors.maxRunsReached": "Max runs reached — edit the loop and increase 'Max runs' to continue",
-    "errors.triggerWhileRunning": "Loop is already running — force run skipped",
+    "errors.maxRunsReached": "Max runs reached - edit the loop and increase 'Max runs' to continue",
+    "errors.triggerWhileRunning": "Loop is already running - force run skipped",
     "format.dash": "-",
     "format.justNow": "just now",
     "format.secsAgo": "{secs}s ago",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loop-task",
-  "version": "1.4.0",
-  "description": "Run commands on repeat. Manage them from a terminal board.",
+  "version": "1.4.1",
+  "description": "Loop engineering toolkit. Run any command on a cadence, in the background, managed from a terminal board. Schedule tests, builds, syncs, or agent prompts.",
   "type": "module",
   "bin": {
     "loop-task": "dist/entry.js"
@@ -29,14 +29,24 @@
   "keywords": [
     "cli",
     "loop",
+    "loop-engineering",
     "repeat",
     "interval",
     "schedule",
     "timer",
     "cron",
     "automation",
+    "automations",
     "devops",
-    "agent"
+    "agent",
+    "ai-agent",
+    "coding-agent",
+    "agent-automation",
+    "claude-code",
+    "codex",
+    "opencode",
+    "background-tasks",
+    "scheduler"
   ],
   "author": "Quique Fdez Guerra",
   "license": "MIT",