Skip to content

Tasks ​

The Tasks view in clusto-app lets you schedule shell commands to run inside a Clusto session. A task is a (name, command, working directory, schedule) tuple persisted by the daemon. When the schedule fires, the daemon spawns a PTY session, runs the command through the platform shell, and records the exit code on the task.

Tasks are executor-agnostic - claude -p "...", ./backup.sh, and pnpm test are all just shell command lines. For interactive Claude back-and-forth use a Session; Tasks are for unattended runs that exit 0 (success) or non-zero (failure).

The Tasks view ​

Route: /tasks, sidebar icon: clock.

The project and node filters are remembered on this device.

Table columns ​

ColumnNotes
Name / CommandDisplay name on top, command line on a secondary line (monospaced, truncated)
ScheduleOne-shot, Cron: <expr>, or Every Nm/Nh/Ns
Statuspending, running, completed, failed, cancelled
Last RunRelative time since the last invocation
Next RunRelative time until the next scheduled run (only meaningful for cron/interval). A paused task shows Resumes in <time> for a timed pause, or Paused for an indefinite one
NodeNode that owns and executes the task (filterable from the header)
ProjectOptional project association (filterable from the header)
Run asThe OS account the task runs as, with where it comes from (task, project, node default or daemon account). On phones it is a "Runs as" line on the task
ActionsView session • History • Edit • Pause / Resume • Run now / Cancel • Delete

Actions ​

  • Run now (▶) - trigger the task immediately, regardless of schedule. The current next_run_at is preserved.
  • Pause / Resume - stop a task from firing without deleting it. See Pausing a task.
  • Cancel (✕, only while running) - kills the underlying session; task status becomes cancelled.
  • View session (↗, when a session exists) - jumps to the session detail view so you can scrub through the captured output.
  • History (clock-with-arrow) - expands an inline panel of the task's past runs (status, duration, attempt, exit code, and a per-run output snapshot).
  • Edit - modify name, command, working directory, project, schedule, env vars, timeout, or retries. Selecting a project auto-fills the working directory from the project (you can still override it), the same way the new-session dialog does.
  • Move - edit a non-running task and choose a different node. Clusto previews the destination project and path, then moves the task and its retained run history after explicit confirmation.
  • Show reports - opens the Reports feed filtered to this task.
  • Delete - removes the task. A running session is not affected; it keeps running until it exits on its own.

Keyboard ​

  • n - open the New Task dialog (when the daemon is connected).
  • F1 palette - Pause <task>… (asks for a length) and Resume <task> for each task.

Pausing a task ​

Any task can be paused, on every plan. Press Pause on its row and pick a length:

  • 1 hour, 4 hours, 1 day, or 1 week
  • Until a date and time you choose (the Resume at field uses your date and time format)
  • Until I resume it - paused indefinitely

While a task is paused:

  • It does not fire on its schedule, and failed-run retries do not fire either.
  • A Paused badge appears on the row. Hover it for Paused until <time> or Paused until resumed.
  • Run now still works. A manual trigger ignores the pause.
  • A run already in progress when you pause finishes normally.

Fires that would have happened during the pause are skipped, not caught up. When the pause ends, a next_run_at already in the past moves to the schedule's next occurrence, so a resumed task does not run a burst of missed slots.

A timed pause ends on its own, at the chosen time: the node's scheduler wakes for it like it does for a scheduled run. Resume ends any pause early. The pause is stored on the owning node and survives daemon restarts.

From the CLI, use clusto task pause and clusto task resume. The Clusto Assistant can propose pausing or resuming a task as an action card; nothing changes until you press Apply.

Defining a task ​

A task has four required pieces:

  1. Command - a single shell command line. Pipes, redirects, env-var expansion, && / || chaining all work because the daemon runs it through sh -c on Unix or cmd /C on Windows.
  2. Working directory - absolute path on the daemon's host. The folder button next to the field browses the task's node so you can pick it instead of typing it. The literal . resolves to the daemon's configured default working dir.
  3. Schedule - one of:
    • One-shot - runs immediately, exactly once.
    • Cron - a 6-field cron expression evaluated in UTC: second minute hour day-of-month month day-of-week (seconds are mandatory - a bare 5-field expression is rejected). An optional 7th year field is allowed. * means "any"; ? means the same but only in the day-of-month and day-of-week fields; steps (*/15), ranges (9-17), and lists (1,15) work; day-of-week is 1=Sun through 7=Sat or names (Mon-Fri); months accept 1-12 or names. Day-of-month and day-of-week are combined with AND. The lowercase shorthands @hourly, @daily, @weekly, @monthly, and @yearly are also accepted; @annually and uppercase forms are rejected. Examples: 0 0 * * * * (every hour), 0 */15 * * * * (every 15 minutes), 0 0 9 * * Mon-Fri (09:00 UTC on weekdays). The create/edit dialog shows a live preview of the next run times so you can confirm the expression before saving.
    • Interval - fires every N seconds, starting N seconds from creation.
  4. Name (optional) - used in the list view and notifications. Falls back to the task's UUID prefix if omitted.

It can also carry optional environment variables, a timeout, and retry settings - see Timeout, retries, and env vars. The create/edit dialog also exposes Notify on success and Notify on failure toggles (notify_on_success / notify_on_failure, both default off): they decide whether a completed run raises a user-facing notification. This is also what the Android Background Notifications poller reports when the app was closed at the time the task finished. A task can also be associated with a project. Beyond filtering and grouping, the project determines the task's execution context the same way it does for an interactive session: when a project is selected the working directory is pre-filled from the project, and at run time the run-as OS user is resolved from the project's run_as_users mapping for this node (see Run as). A blank working directory also falls back to the project's directory.

Run as ​

A task can run as a specific OS account on its node. The create/edit dialog has a Run as field with the node's accounts. Clusto picks the account in this order and uses the first one that is set:

  1. The task's own Run as.
  2. The project's run-as entry for this node.
  3. The project's run-as entry for all nodes (*).
  4. The node's default_session_user.
  5. The daemon's own account.

A blank field means unset, so the next step applies. The Run as column in the task list (and the "Runs as" line on phones) shows the resulting account and which step it came from: task, project, node default or daemon.

The account must exist on the node that runs the task. On Windows, the account must be signed in at the console for a run to start as that user. A task's own account follows the same-account rule as other agent requests: an agent with a limited credential can only create or change tasks that resolve to its own account (see Session Credentials).

From the CLI, clusto task new and clusto task update take --user (an empty value clears it), and the Clusto Assistant's create_task and update_task accept run_as_user.

Choose the execution node ​

Tasks stay node-local, but the app can manage tasks on every online cluster node through the current connection. The Node field in the create dialog chooses which daemon owns and runs a new task. Selecting a project pins the task to that project's node and the node selector reflects that choice. An offline target is shown but cannot be selected for creation.

The table includes a Node column and node filter. Row actions are routed to the task's owning node, so viewing, running, cancelling, editing, and deleting a peer-owned task do not require reconnecting the app.

Move a task between nodes ​

Edit the task and change Node to choose an online destination. The app then requires a destination project owned by that node and an absolute working directory that exists there, followed by an explicit move confirmation. The CLI also supports project-free moves when you provide the destination working directory directly. Moving preserves the task UUID, schedule, configuration, timestamps, and full retained run history. A running task cannot move; cancel it or wait for the run to finish first.

The move is durable and staged. Clusto first pauses the source schedule, stages an inactive copy on the destination, removes the source, and then activates the destination. A failure before source removal automatically aborts the staged copy and restores the source. A failure after source removal is recoverable: retrying the same move operation ID resumes its recorded phase instead of creating a duplicate. The app remembers recoverable operations on the device, and the CLI prints the operation ID and an exact retry command.

Scheduling engine ​

Tasks are scheduled entirely inside clustod - there is no integration with the OS scheduler (cron/crond, systemd timers, or Windows Task Scheduler). The daemon owns a single in-process scheduler:

  • One Tokio loop sleeps until the earliest next_run_at (or timed pause end) and then runs every task whose next_run_at is <= now. Creating, editing, pausing or resuming a task, and a run finishing, wake it early, so a task fires on time (within about a second) instead of on a fixed tick. It never sleeps longer than 30 seconds, which bounds how late a fire can land after the system clock jumps (an NTP correction, a machine waking from sleep).
  • One-shot tasks run immediately on creation rather than waiting for the next tick, so a one-shot you just created starts right away.
  • Cron expressions are parsed and advanced by the Rust cron crate, always in UTC. Interval schedules just add N seconds (the first run lands one interval after creation).
  • Because scheduling lives in the daemon process, tasks are local to each node and not replicated across cluster peers. A task runs on its current owning daemon, which is the creation target until an explicit move completes.

This means clustod must be running for a task to fire. A task whose scheduled time passes while the daemon is down does not backfill - it runs once as soon as the daemon is back up (one catch-up run, not one per missed slot).

Execution model ​

When a task fires:

  1. The scheduler picks the (program, argv) pair for the executor. For shell that's ("/bin/sh", ["-c", command_line]) on Unix and ("cmd", ["/C", command_line]) on Windows.
  2. It creates a new PTY session in the task's working dir and links the session ID back to the task (task.session_id).
  3. The session runs to completion. Its output is captured in the normal session machinery, so the View session link works while it's running and after it finishes.
  4. When the session exits, the scheduler:
    • records a TaskRun with the outcome and a captured output snapshot
    • sets task.last_exit_code to the captured code
    • sets status to completed (exit 0 or signal), failed (non-zero), cancelled (if you hit the cancel button), or treats it as timed_out when the wall-clock timeout fired
    • if the run failed and retries remain, re-fires it after the retry delay (see Timeout, retries, and env vars)
    • for cron/interval schedules, resets the task to pending for the next run (next_run_at was already advanced at spawn)

While a run is in flight the task shows running regardless of schedule type, and reverts to pending (cron/interval) or a terminal status (one-shot) when the run ends. This also acts as an overlap guard: the tick only fires pending tasks, so a run that outlives its interval never spawns a concurrent twin.

The scheduler wakes at each task's next_run_at, so a cron or interval task fires on time, typically within a second of its slot. One-shot tasks run immediately on creation. A task that is due but cannot start (it is being moved to another node) is retried after 30 seconds rather than every second.

Tasks survive daemon restarts. Any task that was running when the daemon exited comes back as pending so the next tick re-evaluates it. Runs that were still in flight when the daemon stopped are marked interrupted at startup: they never reached a real outcome, so history shows them as interrupted rather than failed.

Runs history & output ​

The parent Task still carries a summary of its latest run (last_run_at, last_exit_code, status, and the current session_id). On top of that, the daemon records a bounded per-run history so you can see past runs, not just the most recent state.

Each run is a TaskRun row with its own outcome and a captured output snapshot:

FieldMeaning
id / task_idRun identity and its parent task
attempt1-based attempt within a retry cycle (>1 means a retry)
statusrunning while in flight, then completed / failed / timed_out / cancelled; interrupted if the daemon stopped mid-run
started_at / finished_atRun timing (drives the displayed duration)
exit_codeProcess exit code (null if it never produced one)
outputCollapsed, plain-text, capped output snapshot (tail kept; 64 KB max)

How it behaves:

  • History is retained per task, most recent first. The daemon keeps the newest 10 runs per task plus every failed or timed-out run, so a clean recent streak never hides a past failure; other older runs are pruned on each new insert. The panel's Clear button (ClearTaskRuns) deletes the whole history, failures included. In the Tasks view, the history icon on a row expands an inline panel listing those runs with status, time-ago, duration, attempt, and exit code. Each run with captured output has an Output toggle, and a running run shows a Watch button that attaches to its live session - useful for headless commands like claude -p whose output only appears when they finish.
  • Output is captured at completion. When a run's session exits (or is killed by the timeout), the daemon collapses the PTY output through the same headless VT used for history replay (so spinners/status redraws don't stack) and stores the tail as plain text after removing terminal styling, title commands, and other control sequences. The Tasks view renders that cleaned text directly, and older stored snapshots are cleaned the same way when they are read. Captured output survives the underlying session being torn down - unlike View session, which only works while that session is still live.
  • Live updates. Runs start as running and finish to a terminal status; both transitions are broadcast (TaskRunUpdated) so an open history panel updates without a manual refresh. Listing a task's runs is ListTaskRuns → TaskRunList.
  • Notifications fire per terminal run. A completion that is not followed by a pending retry, and was not cancelled, records a durable task_success or task_failure notification with the task name and exit code - but only when the task's Notify on success / Notify on failure flag (below) is on. These same records are what the Android Background Notifications poller surfaces when the app was closed at completion time.

Wire protocol ​

Tasks are exchanged over the same WebSocket as everything else (see Protocol for the framing). The task-specific messages are:

Task ​

jsonc
{
  "id": "uuid",
  "node_id": "owning node uuid | null",
  "project_id": "uuid | null",
  "name": "string | null",
  "executor": { "kind": "shell", "command_line": "pnpm test" },
  "working_dir": "/abs/path",
  "schedule": { "type": "one_shot" }
                | { "type": "cron", "expression": "0 0 3 * * *" }
                | { "type": "interval", "seconds": 3600 },
  "status": "pending | running | completed | failed | cancelled",
  "created_at": "RFC3339",
  "last_run_at": "RFC3339 | null",
  "next_run_at": "RFC3339 | null",
  "session_id": "uuid | null",
  "last_exit_code": "i32 | null",
  "env": { "KEY": "value" },        // extra env vars injected into the run
  "timeout_seconds": "u64 | null",  // wall-clock kill; null = no limit
  "max_retries": 0,                 // re-fires after a failed run
  "retry_delay_seconds": 0,         // wait between a failure and its retry
  "notify_on_success": false,       // alert on a successful completion
  "notify_on_failure": false,       // alert on a failed / timed-out completion
  "run_as_user": "string | null",   // the task's own run-as account; null = unset
  "resolved_run_as": { "user": "string | null", "source": "task | project | node_default | daemon" },  // what will actually run
  "pause": { "paused_at": "RFC3339", "until": "RFC3339 | null" } | null  // null = not paused; until null = paused until resumed
}

A TaskRun (per-run history record):

jsonc
{
  "id": "uuid",
  "task_id": "uuid",
  "session_id": "uuid | null",
  "attempt": 1,
  "status": "running | completed | failed | timed_out | cancelled | interrupted",
  "started_at": "RFC3339",
  "finished_at": "RFC3339 | null",
  "exit_code": "i32 | null",
  "output": "string | null"         // collapsed, capped (64 KB tail)
}

The executor field is discriminated by kind. Today there is one variant:

  • {"kind": "shell", "command_line": "<line>"} - runs through the platform shell. Future variants (e.g. a dedicated webhook executor) can be added without breaking existing tasks because the wire format and the SQL schema both treat the executor as a single tagged JSON blob.

Client → Daemon ​

MessagePayload
CreateTask{ name?, executor, working_dir, schedule, project_id?, run_as_user?, env, timeout_seconds?, max_retries, retry_delay_seconds, notify_on_success, notify_on_failure, node_id? }
ListTasks- returns the receiving node's tasks merged with reachable peers
GetTask{ task_id, node_id? }
ListTaskRuns{ task_id, node_id? } - fetch a task's run history from its owner
UpdateTask{ task_id, name?, executor?, working_dir?, schedule?, project_id??, run_as_user?, env?, timeout_seconds?, max_retries?, retry_delay_seconds?, notify_on_success?, notify_on_failure?, pause?, node_id? } (only provided fields are changed; timeout_seconds and project_id are nested options so they can be cleared - inner null detaches the project; pause is {"type":"pause","until":<RFC3339 or null>} to pause (null = until resumed) or {"type":"resume"} to end a pause; run_as_user is absent to leave it alone, null to clear it, or an account name to set it)
DeleteTask{ task_id, node_id? }
CancelTask{ task_id, node_id? }
TriggerTask{ task_id, node_id? } (run now)
ClearTaskRuns{ task_id, node_id? } - delete the task's whole run history
MoveTask{ operation_id, task_id, source_node_id, target_node_id, destination_project_id?, destination_working_dir } - durably migrate a non-running task and its retained history
AbortTaskMove{ operation_id, source_node_id, target_node_id } - abort a prepared move before source removal commits

Daemon → Client ​

MessagePayload
TaskList{ tasks: Task[] } - response to ListTasks and GetTask
TaskCreated{ task }
TaskUpdated{ task } - broadcast to every connected client on create, status change (run start, session exit, cancel), and manual edit
TaskDeleted{ task_id } - broadcast to every connected client when a task is deleted
TaskRunList{ task_id, runs: TaskRun[] } - response to ListTaskRuns, most recent first
TaskRunUpdated{ run } - fired when a run starts or finishes
TaskMoved{ operation_id, task } - migration completed and the task is active on the destination
TaskMoveFailed{ operation_id, task_id, message, recoverable } - migration stopped; retry the same operation ID when recoverable
TaskMoveAborted{ operation_id, task_id } - a prepared migration was rolled back

Persistence ​

Tasks live in the SQLite tasks table (extended through schema v26), with per-run history in task_runs and the durable cross-node move journal added in schema v44:

sql
CREATE TABLE tasks (
    id            TEXT PRIMARY KEY,
    project_id    TEXT REFERENCES projects(id) ON DELETE SET NULL,
    name          TEXT,
    executor      TEXT NOT NULL,    -- JSON of TaskExecutor (tagged by `kind`)
    working_dir   TEXT NOT NULL,
    schedule      TEXT NOT NULL,    -- JSON of TaskSchedule
    status        TEXT NOT NULL,
    created_at    TEXT NOT NULL,
    last_run_at   TEXT,
    next_run_at   TEXT,
    session_id    TEXT,
    last_exit_code INTEGER,
    env                 TEXT,       -- JSON object of env vars (v23)
    timeout_seconds     INTEGER,    -- v23
    max_retries         INTEGER NOT NULL DEFAULT 0,   -- v23
    retry_delay_seconds INTEGER NOT NULL DEFAULT 0,   -- v23
    notify_on_success   INTEGER NOT NULL DEFAULT 0,   -- v26
    notify_on_failure   INTEGER NOT NULL DEFAULT 0    -- v26
);

CREATE TABLE task_runs (           -- v23
    id           TEXT PRIMARY KEY,
    task_id      TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
    session_id   TEXT,
    attempt      INTEGER NOT NULL DEFAULT 1,
    status       TEXT NOT NULL,
    started_at   TEXT NOT NULL,
    finished_at  TEXT,
    exit_code    INTEGER,
    output       TEXT
);

CREATE TABLE task_moves (          -- v44
    operation_id TEXT PRIMARY KEY,
    task_id      TEXT NOT NULL,
    role         TEXT NOT NULL,     -- source or target
    phase        TEXT NOT NULL,
    bundle_json  TEXT NOT NULL,
    last_error   TEXT,
    updated_at   TEXT NOT NULL
);

Run history is pruned on each insert to the newest 10 rows per task, keeping every failed or timed-out row. Deleting a task cascades to its runs. Move journal rows make a repeated operation ID idempotent across retries and daemon restarts.

Tasks are local to each daemon. They are not replicated across cluster peers - unlike sessions and projects, every daemon runs its own task list. Use the app's node selector or clusto task new --node <NODE_ID> to schedule one on a specific online node. The CLI accepts --node <NODE_ID> on task list, get, update, delete, cancel, and trigger commands. Omitting the flag keeps the connected node as the default target.

Timeout, retries, and env vars ​

  • Timeout (timeout_seconds) - a wall-clock limit per run. A run that exceeds it is killed and recorded as timed_out (and counts as a failure for retry purposes). null/0 means no limit.
  • Retries (max_retries, retry_delay_seconds) - after a run fails (or times out), the task re-fires up to max_retries more times, waiting retry_delay_seconds between attempts. Each retry increments the run's attempt. Retry bookkeeping is in-memory and resets on success, on exhaustion, or on daemon restart. A cancelled run never retries.
  • Env vars (env) - a key/value map injected into the run's environment on top of the daemon's own (task values win on conflict). In the UI, enter one KEY=value per line. When the task runs as another OS user (Run As), the values are applied inside that user's process, after the account switch, so the privileged helper that performs the switch never sees them: a task cannot use LD_PRELOAD or a similar variable to make that helper load code. A Run As task whose env has a name that is not a valid shell variable name (for example FOO-BAR) fails to start with a clear error. A task's own HOME, SHELL, USER and LOGNAME now take effect, since they are set after the switch. A task's env cannot replace the run's own CLUSTO_TOKEN or HIVE_TOKEN, which always carry the run's credential.
  • Injected run context - every run also gets CLUSTO_TASK_ID, CLUSTO_TASK_RUN_ID, CLUSTO_PROJECT_ID (when the task has a project), and the local daemon connection details, so clusto report post inside the run links a report to it with no extra flags. The CLUSTO_TOKEN a run gets is the node admin token for a run that runs as root or as the daemon's own account, and a limited session credential for a run that runs as another account (when that release flag is on). A credential works only on this machine and stops working when the run ends.

Tasks created by an agent ​

An agent inside a session that holds a limited credential can list tasks and create, change, delete, trigger, cancel, pause or resume its own, with these limits (see Session Credentials). It does this with the clusto task CLI or the clusto_task_create, clusto_task_update, clusto_task_delete, clusto_task_trigger, clusto_task_cancel, clusto_task_pause and clusto_task_resume tools of clusto mcp (see Knowledge). Agents use them only when you ask. The Clusto Assistant has no task write tool; it proposes an action card instead.

  • The task must belong to the node the credential was issued by, and its runs must resolve to the same OS account as the agent (the project's Run As, else the node's default session user). Anything else is refused with a message naming the account.
  • Task env values are masked in what the agent reads back, and loader and runtime variables (LD_*, DYLD_*, MALLOC_*, GLIBC_TUNABLES, TMPDIR and a few similar glibc names) cannot be set. Set them inside the task's command instead.
  • Moving a task to another node is not available to a limited credential.

Reports ​

Tasks can publish their results to the Reports feed with clusto report post or the clusto report mcp MCP tools - a markdown summary, a chart, or any file. When a run fails or times out and no retry is pending, the daemon posts an Error report on its own with the exit code, attempt, duration, and the tail of the captured output, so failed automations stand out in the feed.

When a Claude Code run posts a report, the report also records the run's own Claude conversation (from CLAUDE_CODE_SESSION_ID and CLAUDE_PROJECT_DIR), so you can continue that conversation from the report.

Caveats ​

  • Shell injection is on you. The command line goes verbatim into sh -c / cmd /C. Don't paste untrusted input.

Clusto - remote AI coding agents over WebSocket.