Background Tasks & Scheduling

Command Code no longer sits and waits. Dev servers, log tails, long test suites, parallel research agents, and scheduled reminders can all run in the background while the agent keeps working - and the agent gets woken up when there's something to look at, instead of polling.

This page covers the full background surface:

Background shell commands

Any shell command can be started as a tracked background task instead of blocking the turn. The agent passes run_in_background: true to shell_command:

• The tool returns immediately with a task id, status, PID, working directory, and the path of an on-disk output log.
• The command's combined stdout/stderr is mirrored to that log file as it runs, so the full output is always on disk and tail-able - even output that never fits in the model's context.
• The task is listable with shell_tasks, readable with shell_output (the bash_output / task_output names remain as aliases), and stoppable with kill_shell or task_stop.

Task ids are short and stable for the session: shell tasks start with s (s0abc123), monitors with m (m0abc123). Logs live under the OS temp directory (<tmp>/commandcode/shellout/<timestamp>-<taskId>.log).

Reading output: shell_output

shell_output reads the output a background task has accumulated so far, plus whether it's still running:

• Takes the task id returned by shell_command (a raw runtime background id also works).
• Output is tail-bounded to 30,000 characters inline - a chatty dev server can't flood the context. When the buffer exceeds the cap, the result keeps the newest output and prepends a note naming how much was cut and where the full log lives on disk:

The newest output matters most (test verdicts, final errors); for anything older, the agent greps or reads the on-disk log directly instead of re-pulling megabytes through the context window.

shell_output also waits, so reading a background task never has to become a poll loop:

A timeout is a normal outcome, not an error - the result explains that the process is still quiet and how to keep waiting. Process output is fenced as untrusted data, the same way task_output fences it. An id the tool has never seen is reported as an error naming shell_tasks; it is never rendered as [finished], because telling the model that a mistyped id completed successfully is the one answer it will confidently act on.

Reading output: task_output

task_output is the richer read - it unifies "wait for my build" and "peek at my server" in one tool:

Over the cap, task_output keeps the tail and points at the on-disk log for the rest. Every result reports a retrieval status (success, not_ready, or timeout), the task's status, exit code, signal, and log path.

Untrusted-output fencing. Output from a child process is data, not instructions. task_output wraps it in an explicit fence and defangs any fence-marker collisions inside the content, so log output can never masquerade as user or system instructions:

Listing tasks: shell_tasks

shell_tasks lists every tracked shell and monitor task - id, kind, status, PID, command, cwd, timestamps, and output log path. By default it includes settled tasks (completed, failed, stopped); pass includeStopped: false to show only what's currently running.

Task status is reconciled lazily on every read: a task whose process exited since the last look settles to completed (exit 0) or failed (anything else) the moment anything lists or reads it.

Stopping tasks: kill_shell and task_stop

kill_shell stops a background task or terminates a process - by exactly one of three targets:

Group-kill safety. Only tracked tasks are ever stopped by process group. An arbitrary PID the model asks to kill is never escalated to a group kill - signalling -pgid for an untracked PID could take down every unrelated process sharing that group, including your own shell. The tool also rejects non-positive PIDs outright: to kill(2), 0 and -1 are broadcasts, not processes.

No false success. kill_shell verifies the target actually exists before killing (a process it can't signal due to permissions still counts as alive), and reports a real error if the process survives the force kill - never a false "successfully killed".

task_stop is the taskId-focused sibling: it stops a tracked task by id (SIGTERM to its process group), marks it stopped in the registry, and distinguishes "unknown id" from "already settled" (echoing back the settled status). Use task_stop for tasks you started; use kill_shell when you need to target a PID or free a port.

Exit-code honesty

Command Code reports exit codes the way your own shell would:

• Signal deaths are never exit 0: A child killed by a signal reports the shell-convention code 128 + N (SIGKILL → 137, SIGTERM → 143) alongside the signal name, so an OOM-killed test run reads as Exit code: 137 / Signal: SIGKILL, not a silent success.
• Conventional non-error codes are annotated: Exit 1 from grep/rg means "No matches found", from diff/cmp "Files differ", from test/[ "Condition is false" - the result names the meaning (Exit code: 1 (No matches found)) so a result is never mistaken for a failure.

Monitors: watch without polling

monitor_command starts a long-running monitor - a tracked background task purpose-built for things you observe over time: log tails, watch commands, dev-server health streams, file watchers. It always runs in the background and returns a monitor task id, PID, cwd, and output log path.

Scheduled wake-ups - the agent never polls

With notify: "scheduled" (the default), the runtime automatically wakes the agent twice:

1. Once after checkAfterMs - a tiny hidden ping saying the check is due.
2. Again when the monitor exits - including its final status, exit code, and signal.

The ping deliberately contains no monitor output; it names the task, PID, and log path and tells the agent to call monitor_events if the output is actually needed. Wake-ups arrive as automated user turns between the agent's turns - the agent is explicitly instructed not to poll or repeatedly call monitor_events while waiting. Start the monitor, keep working, get woken when it matters.

Delta reads: monitor_events

monitor_events reads new output from a monitor without rereading the whole log:

• Each monitor tracks a stored byte offset. Call monitor_events({ taskId }) and it reads from the stored offset and advances it - repeated calls stream forward through the output.
• Pass an explicit fromOffset for a one-off read from a specific byte position (the stored offset is left alone).
• maxBytes defaults to 8,192 bytes per read (capped at 1 MiB), keeping monitor reads cheap.

Monitors have full lifecycle parity with background shells: listable via shell_tasks, readable via monitor_events / task_output, stoppable via kill_shell or task_stop by taskId.

The structured task ledger

task_create / task_update / task_list / task_get maintain a durable, dependency-aware work ledger - a persistent upgrade over the session checklist for coordination-heavy work.

What makes it a ledger rather than a checklist:

• Stable ids - every task gets a monotonic id that survives restarts.
• Persistence - tasks are stored on disk (under the OS temp dir), so restarts and other processes sharing the same list id see one shared list. The list id can be pinned across processes with the COMMAND_CODE_TASK_LIST_ID environment variable (default: session) - that's how sub-agents and multi-process handoffs share one board.
• Dependency edges - blockedBy / blocks encode ordering. Edges are symmetric and can be added at create time or later.
• Owners and metadata - tasks carry an owner (set it to claim a task) and arbitrary key/value metadata (merged on update; set a key to null to delete it).
• Plan-safe - all four tools mutate only the task list, never the workspace, so they work in plan mode.

The lifecycle

Tasks move pending → in_progress → completed (with deleted as a terminal removal that also clears the task from all dependency lists). The workflow rules match the checklist: mark a task in_progress before starting it, completed immediately after finishing, keep exactly one task in_progress at a time, and never mark something completed while tests fail or work is partial.

Completing a task reports which blocked tasks it just unblocked, so the next piece of work is picked up right away. task_list shows id, status, subject, owner, and unresolved blockers (completed blockers are dropped from the display) plus a completion tally; task_get returns a task's full detail - read it before starting work, and verify its blockedBy list is empty.

When to use the ledger

Use task_create only when its features matter: handing work to sub-agents or sharing a list across processes, encoding ordering as dependency edges, work meant to outlive the session, or capturing a plan in plan mode. For an ordinary in-session checklist - and always when you ask for "todos" - todo_write is the tool.

todo_write: the session checklist

todo_write is the session TODO list - the visible progress tracker for multi-step work in the current conversation:

• Every call carries the complete list (it replaces, never appends) of {content, status, activeForm} items. content is the imperative form ("Run tests"); activeForm is the present-continuous label shown while the item is in progress ("Running tests").

• The list renders live in the TODOS panel in the TUI, driven directly from the tool input.

• The /todos manager (also ctrl+x) lets you edit the list from the TUI - and your edits stick: items you delete stay deleted (the model is told not to re-add them), and items you mark completed stay completed (a stale resend can't un-finish your work). When a plan finishes that you partly drove, the model is told to attribute honestly.

  Key	Action
  ↑ / ↓	Move the selection
  c	Mark the selected item completed
  x	Remove the selected item
  a	Mark the whole plan done (clears the list)
  ctrl+x / esc	Close the manager

• When every item is completed (or an empty list is submitted), the checklist clears so the next task starts from a blank slate.

• The tool pushes back on sloppy usage: it calls out identical resubmissions, silently dropped unfinished items, and multiple simultaneous in_progress items, and nudges for a verification step before a large plan is closed out.

Rule of thumb: todo_write for this session's progress; the task_* ledger for durable, dependency-ordered, multi-agent work.

Tasks vs. /todos at a glance

Both are model-driven - there is no command that creates one by hand. The agent decides to create, update, and complete them as part of doing the work, and you see the result in the feed.

Background sub-agents

The agent tool can run a sub-agent in the background: pass run_in_background: true (or use an agent definition with background: true) and the tool returns immediately with an agent id while the child keeps working:

Background agents are detached from the parent turn: cancelling or aborting the spawning turn does not kill them - each runs under its own abort controller, and only an explicit kill stops it. Statuses are running, completed, failed, and killed.

Complete guideCustom Agents→

Define the sub-agents you fan out to: frontmatter fields, tool and model scoping, where agent files load from, and the built-in agents.

Collecting results: agent_output

This is the fan-out pattern: launch several background agents on independent subtasks, keep working on the main thread, then wait on each as its result becomes load-bearing.

The Background panel in the TUI

Running background work is always visible in the TUI:

• The bottom status bar shows a live badge with running counts - "3 shells, 2 monitors" - plus a ↓ to manage hint whenever anything is running.
• Ctrl+B (or ↓ from the empty input) toggles the Background panel: a manager overlay listing every shell and monitor task, grouped by kind when both exist, with live status colors (running, completed, failed, auto-stopped, stopped).

Inside the panel:

The panel polls the shared task registry once a second, so it reflects exactly what shell_tasks would report.

Scheduled tasks and loops

Use /loop when a task should run now and be checked again within a time period in the same conversation. It is a bundled skill backed by the scheduler, so it appears in the slash menu and uses deterministic parsing rather than asking the model to guess the cadence. A self-paced loop starts only from a /loop you type; if you ask for one in prose, the agent asks you to run the command.

Fixed loops

Put an interval before the task or end the task with an every ... clause:

Intervals accept s, m, h, and d. Cron has one-minute resolution, so seconds round up to a minute. Cadences that do not map cleanly to a five-field cron step are normalized to the closest clean schedule, and the confirmation tells you what was selected. Multi-day steps follow cron's calendar fields and restart at the beginning of each month. The first pass always runs immediately.

Fixed loops receive deterministic jitter to spread API traffic. A recurring task may fire up to 10% of its interval late, capped at 15 minutes. The offset comes from the task id, so a task keeps the same offset after resume.

Self-paced loops

Without an interval, the agent decides when another check would be useful. Each iteration chooses a delay from one minute to one hour, records a short reason, and replaces the previous pending wakeup instead of stacking another task. This works well when a build needs short checks at first and longer waits after activity settles.

Self-paced wakeups are not jittered. They use the chosen delay directly and show that choice in the iteration result. Only one self-paced loop is active per conversation; starting another replaces the pending one.

When an iteration finishes without choosing another check or stopping, Command Code schedules one 20-minute safety check. If that fallback iteration also omits a next action, the loop ends. This catches an accidental omission without creating a loop that cannot stop.

The default task and loop.md

A /loop command without a specified task uses a compact maintenance task that's pre-specified. For example, continue unfinished conversation work, tend actionable pull-request or CI issues on the current branch, then make one bounded quality pass if nothing is pending. It does not authorize unrelated work or widen permission for destructive actions.

Replace the default maintenance task with a markdown file:

The file is read again for every default-task iteration (running a bare /loop), so edits affect the next check. Empty files are ignored, and content beyond 25,000 bytes is truncated. A task supplied directly to /loop does not read either file.

Stop and manage loops

Press Esc to stop pending /loop work in the active conversation. This cancels both fixed and self-paced loops but leaves ordinary reminders and schedules alone. A self-paced iteration can also stop itself as soon as its task is complete.

Ask naturally to inspect or cancel scheduled work:

cron_list returns fixed schedules and self-paced loops with their eight-character ids. cron_delete accepts either kind of id. A conversation can hold at most 50 scheduled tasks.

One-time reminders and direct schedules

You do not need /loop for a one-shot task. Write a prompt to create a task that deletes itself after firing:

The underlying tools are:

cron_create accepts minute hour day-of-month month day-of-week. Wildcards, values, steps, ranges, and comma lists are supported; name aliases and extended syntax are not. When both day-of-month and day-of-week are constrained, either field may match. Times use your local timezone.

Scope, resume, and firing behavior

Normal scheduled tasks belong to the conversation. Closing Command Code pauses them. --resume or --continue restores recurring tasks that are still within their seven-day lifetime and one-shots whose fire time is still ahead. A fresh conversation does not run tasks from another conversation.

The scheduler checks once a second and only submits a due prompt between turns. If the agent is busy, one due event waits for the turn to finish; missed intervals never produce a catch-up burst. Scheduled text is fenced as task data before it reaches the model.

A scheduled /skill reference runs only when that skill is enabled and permits model invocation. Manual-only skills, built-in commands, and MCP prompt commands remain plain task text.

Pass durable: true to cron_create only for an explicitly requested machine-level schedule that should not depend on resuming a conversation. Those jobs live in ~/.commandcode/cron/jobs.json. A durable one-shot missed while Command Code was closed asks for confirmation on the next launch, and a lease prevents two open sessions from firing the same durable task.

Recurring tasks expire seven days after creation. A running fixed task gets one final fire at expiry; a self-paced loop stops when it reaches the limit. Re-create a task before expiry or use an external scheduler when it must run indefinitely.

One-shots at :00 or :30 may fire up to 90 seconds early. Choose another minute when exact timing matters. Self-paced wakeups do not use this jitter.

Where /loop runs

/loop needs an interactive, top-level conversation. It is not available in these places:

Kill switches

The sleep tool

sleep is a first-class wait: the agent pauses without holding a shell process, and without burning the agent loop the way shell_command sleep N would (which is blocked anyway for N ≥ 2 seconds in the foreground).

While sleeping, the tool streams a once-per-second progress line to the feed (Sleeping - 1m 30s / 5m - waiting for CI), and you can interrupt it at any time. It's read-only and concurrency-safe, so it can run alongside other tools in the same batch.

Long waits are chunked. Each call is capped (default 10 minutes); a capped result names the remaining time so the agent calls sleep again to continue - each wake-up is one API round trip, which also keeps the prompt cache warm across genuinely long waits.

Duration policy lives in settings.json:

minDurationMs raises short sleeps (throttling wake-up frequency and API calls); maxDurationMs caps long ones per call - set it to -1 to remove the cap entirely. When a request is reshaped by either edge, the result says so and by how much.

Practical workflows

Watch a dev server while coding

Start the server as a monitor, keep working, get woken when something happens:

Command Code starts pnpm dev via monitor_command (scheduled notify), works on the fix, gets the hidden wake-up ~45 seconds in, and reads only the new log output via monitor_events - no polling, no context flooded with server chatter. If the server needs restarting, kill_shell({ taskId }) frees it cleanly (or kill_shell({ port: 3000 }) if something else is squatting on the port).

Long test suites and builds

shell_command with run_in_background: true starts the suite; the refactor continues; a blocking task_output({ taskId }) collects the verdict - waiting up to its timeout for the run to settle and returning the tail with the exit code. A signal-killed run reports 128+N, never a false pass.

Watch a release on a schedule

The task runs once immediately, then becomes a conversation-scoped fixed loop. Resume the conversation to keep it going after a restart, press Esc to stop it, or use its id with cron_delete.

Fan out research to background agents

Three agents launch with run_in_background: true; each returns an agent_id immediately. The main thread keeps its context clean while the agents dig, then agent_output waits on each in turn and merges the findings. A stuck agent gets action: "kill"; the launching turn can even be interrupted without losing any of them.

Wait for something external

One sleep({ seconds: 480, reason: "waiting for deploy" }) - no shell held, progress streamed, and if you type "it's done early", the sleep wakes within a second and the smoke test starts immediately. For a fixed time instead: sleep({ until: "14:30" }).

Choosing the right tool

Next steps

• Interactive mode: the TUI where the Background panel and TODOS panel live
• Custom agents: define the sub-agents you fan out to
• Hooks: deterministic guards around every tool call, background ones included
• Questions? Join our Discord community