Loops

Overview

A Loop is a recurring agent run built on the trigger router: a cron-source subscription bound to an agent. It’s the governed, observable wrapper over a raw cron job — creating a loop records the binding and creates the backing cron job that executes it.

Command	Description	Cost
`naive loops create --schedule <cron> --prompt <text>`	Create a recurring agent run	Free (cost on each firing)
`naive loops list`	List all loops	Free
`naive loops get <id>`	Show one loop	Free
`naive loops update <id> [--no-active\|--active] ...`	Pause/resume or edit a loop	Free
`naive loops run <id>`	Run once now	Credits (based on work)
`naive loops remove <id>`	Delete a loop (and its backing cron job)	Free

Create a Loop

naive loops create \
  --schedule "0 9 * * *" \
  --prompt "Review overnight email and summarize what needs my attention" \
  --name "Morning inbox triage"

Options

Flag	Description
`--schedule <cron>`	Required. Cron expression (see below)
`--prompt <text>`	Required. Prompt to run each time the loop fires
`--name <name>`	Human-readable name for the loop
`--profile <name>`	Agent profile to run as (defaults to the CEO)
`--user <id>`	Target a specific tenant user

Schedule Format (Cron Expression)

Expression	Meaning
`0 9 * * *`	Every day at 9:00 AM UTC
`/30 * * *`	Every 30 minutes
`0 /6 * *`	Every 6 hours
`0 0 * * 1`	Every Monday at midnight UTC

Output

The response includes the created loop and the cron_job_id of the backing executor (null if no runtime is reachable yet — the binding still persists and syncs later).

{
  "success": true,
  "action": "loops.create",
  "result": {
    "loop": {
      "id": "loop_01H...",
      "name": "Morning inbox triage",
      "schedule": "0 9 * * *",
      "active": true,
      "source": "cron",
      "kind": "loop",
      "target": { "prompt": "Review overnight email and summarize what needs my attention" }
    },
    "cron_job_id": "cron-abc-123"
  },
  "hints": [
    "Loop created (id: loop_01H...)",
    "Schedule: 0 9 * * *",
    "Name: Morning inbox triage",
    "Backing cron job: cron-abc-123"
  ]
}

List Loops

naive loops list

Returns all loops with:

id, name, schedule (cron expression), active
target (prompt + optional profileName)
cronJobId of the backing executor

Get a Loop

naive loops get loop_01H...

Shows a single loop’s full details.

Update a Loop (pause / resume / edit)

Pausing and resuming a loop leaves the runtime untouched — only the binding row changes.

naive loops update loop_01H... --no-active            # pause (won't fire on schedule)
naive loops update loop_01H... --active               # resume
naive loops update loop_01H... --prompt "New instructions"
naive loops update loop_01H... --name "Renamed loop" --profile support

Options

Flag	Description
`--active` / `--no-active`	Resume / pause the loop
`--name <name>`	New human-readable name
`--prompt <text>`	New prompt to run each firing
`--profile <name>`	New agent profile to run as
`--user <id>`	Target a specific tenant user

Run Now

Fires the loop immediately, regardless of schedule. The regular schedule is not affected. Returns the run_id of the triggered run.

naive loops run loop_01H...

Remove a Loop

naive loops remove loop_01H...

Permanently deletes the loop binding and best-effort removes the backing cron job. Cannot be undone.

Typical Workflow

# 1. Create a recurring agent run
naive loops create --schedule "0 9 * * *" --prompt "Summarize overnight email" --name "Morning triage"

# 2. Test it immediately
naive loops run loop_01H...

# 3. View all loops
naive loops list

# 4. Pause if needed
naive loops update loop_01H... --no-active

# 5. Delete when done
naive loops remove loop_01H...

Loops vs. Cron Jobs

naive cron is a push-through to the runtime’s scheduler. A Loop wraps it with a binding-registry row and per-run delivery status, and pauses/resumes without touching the runtime. On a Tower the executor is the box’s Hermes gateway cron; in the cloud it’s the sidecar cron. See Loops for the API-level reference.

CLI Reference

Multi-tenant

Primitives

Overview

Create a Loop

Options

Schedule Format (Cron Expression)

Output

List Loops

Get a Loop

Update a Loop (pause / resume / edit)

Options

Run Now

Remove a Loop

Typical Workflow

Loops vs. Cron Jobs

​Overview

​Create a Loop

​Options

​Schedule Format (Cron Expression)

​Output

​List Loops

​Get a Loop

​Update a Loop (pause / resume / edit)

​Options

​Run Now

​Remove a Loop

​Typical Workflow

​Loops vs. Cron Jobs

Overview

Create a Loop

Options

Schedule Format (Cron Expression)

Output

List Loops

Get a Loop

Update a Loop (pause / resume / edit)

Options

Run Now

Remove a Loop

Typical Workflow

Loops vs. Cron Jobs