Loops

Overview

A Loop is a named, persisted workflow that runs an ordered list of stages, each of which is a single goal command executed by a worker agent. A trigger — manual or interval — decides when the loop fires.

The headless LoopEngine (packages/nikcli/src/loop/engine.ts) owns the interval timers via the core Scheduler with scope: "instance", so scheduled loops keep firing when the TUI is closed. The TUI feature plugin (packages/tui/src/feature-plugins/loops/) is a thin client over the SDK: it subscribes to bus events for live status, and uses the SDK to create, run, pause, resume, and delete loops.

Concepts

Loop schema

All persisted types live in packages/nikcli/src/loop/schema.ts as zod schemas.

Trigger

export const LoopTriggerSchema = z.discriminatedUnion("kind", [
  z.object({ kind: z.literal("manual") }),
  z.object({ kind: z.literal("interval"), everyMs: z.number().int().positive() }),
])

Stage

Definition

Run

Operational bounds

Engine lifecycle

1. Register — the TUI or HTTP/SDK client calls LoopEngine.upsert(def), which persists the definition through LoopRepo and arms (or re-arms) the interval timer in the core Scheduler.
2. Fire — the Scheduler calls the engine's run callback. The engine claims the per-loop single-flight slot and a slot in the global MAX_CONCURRENT_RUNS = 3 pool.
3. Drive — the engine runs the stages in order. Each stage is a single SessionPrompt.command({ command: "goal" }) call. The agent's own goal loop (src/session/goal.ts) does the until-done iteration.
4. Persist — every stage transition renews the lease/heartbeat and writes a LoopRun record. Status flips to complete, error, or timeout when the run ends.
5. Reconcile — on next boot, restore() finds every running run whose lease is older than LOOP_RUN_LEASE_MS and reconciles it to orphaned, then re-arms every interval loop.

Triggers and stages

Manual trigger

Manual loops never fire on a timer. They are started by the user through the TUI loop dialog or the HTTP/SDK interface. Use a manual loop when the work is infrequent or you want the user to opt in every time.

Interval trigger

Interval loops fire every everyMs milliseconds. The smallest accepted interval is 30s; the largest is 30 days. The engine re-arms the timer on every run start and after every run finish.

Stages

Stages run sequentially inside a single run. A stage's objective is the prompt fed to a fresh goal session. Stages share the loop's run id but each spawns its own session, so the previous stage's session is referenced by id but not reused.

# A simple two-stage loop that triages issues then drafts a fix
stages:
  - name: triage
    agent: plan
    objective: "Triage the open issues in this repo and rank by impact."
  - name: draft-fix
    agent: build
    objective: "Pick the top issue and draft a fix as a draft PR."

Auto-PR on completion

Set createPR: true on a loop definition to have the engine push the worktree and open (or update) a GitHub pull request every time a run finishes with status: "complete". The engine reuses one branch per loop (loop/<id>), so a long-running loop accumulates its work on a single PR instead of opening a fresh one each tick.

When the hook succeeds, the run record is updated with a pullRequest block (number, url, branch, base, action: created or updated) and the TUI/mobile history view deep-links straight to the PR.

HTTP and SDK operations

There is no top-level nikcli loop command. Manage loops through the TUI or the generated SDK, which calls the Effect HttpApi routes below.

curl http://127.0.0.1:4096/loop
curl -X POST http://127.0.0.1:4096/loop/lop_abc123/run
curl -X POST http://127.0.0.1:4096/loop/lop_abc123/pause
curl -X POST http://127.0.0.1:4096/loop/lop_abc123/resume

Bus events

The engine publishes typed bus events for clients to subscribe to. They live next to the engine in packages/nikcli/src/loop/engine.ts.

TUI surface

The TUI loop feature-plugin lives in packages/tui/src/feature-plugins/loops/. It mirrors the mission plugin and exposes:

• Loop home view — list of all loops with status chips, last run time, and quick actions (run, pause, resume, delete).
• Loop detail view — per-stage list, current run highlight, run history (last 50), and the live session id of the active stage.
• Draft dialog — pick a template, edit stages, and create a loop without leaving the TUI.
• Run dialog — trigger an immediate run with optional one-off context (--text).

Mobile surface

The mobile app exposes the same surface as a dedicated Loops tab. The screen lists every loop with a status chip, schedule summary, last-run timestamp, and quick actions. The detail screen edits the definition, fires manual runs, and pages through run history.

See Mobile for the full mobile walkthrough.

Failure modes

Source anchors