Background tasks, queue, and loops

• **Background commands and sub-assistants** run off the foreground turn.
• **The prompt queue** holds what you type while a turn is already running.
• /loop schedules a recurring prompt. It is visible and runnable only when the session advertises the scheduler_create tool.

/queue and /tasks are pager builtins. They commit a read-only snapshot into scrollback. They work in every render mode. The interactive panes (queue, tasks) exist in the fullscreen TUI; minimal mode uses the slash commands instead.

Choose by when you need an answer

A compile, a test suite, or a dev server should not freeze the conversation. A follow-up you already know you will send should not wait for you to stare at a spinner. A health check every few minutes should not be you repeating /loop by hand.

Demote a running command: `Ctrl+B`

While a foreground shell command is running, Ctrl+B sends it to the background. That is the only backgrounding shortcut. The process keeps running; you get a notification when it finishes. Track it in the tasks pane (Ctrl+G) or with /tasks.

The assistant can also start a command already in the background (run_terminal_command with background: true) and later call get_command_or_subagent_output or wait_commands_or_subagents. kill_command_or_subagent stops a task or child.

Prompt queue: `/queue`

If you submit while a turn is running, Matcha queues the text and sends it when the turn ends.

• **Fullscreen:** Ctrl+; toggles the queue pane (on some macOS VS Code-family terminals, Ctrl+4 is primary; Ctrl+' is an alternate). Edit and reorder there.
• **Any mode:** /queue appends a system block listing queued prompts, or Queue is empty. It does not edit the queue. Session-scoped: no active session → error.

Snapshot running work: `/tasks`

/tasks lists, as a system block:

• Workflow runs (if any)
• Sub-assistants
• Background commands
• Monitors and scheduled /loop tasks

Killing or attaching is not done from /tasks; use the tasks pane (Ctrl+G) in the fullscreen TUI. Session-scoped, like /queue.

The still-running status line above the prompt counts commands, monitors, loops, and background sub-assistants while the assistant looks idle. Completions land in the transcript; the counts stay on that line only.

Recurring prompts: `/loop`

/loop [interval] <prompt>

/loop is gated on scheduler_create. If that tool is not in the session's advertised toolset, /loop is hidden from the menu and a typed invocation does not run. Empty args print usage; they do not invent a default interval.

/loop 5m Check if the test suite passes and report any failures
/loop 2h Summarize new commits since the last check
/loop check deploy status every hour

A leading token of the form <number><s|m|h|d> (non-zero) is treated as the cadence for the on-screen preview. Anything else — including natural language at either end — is passed to the model, which must turn it into scheduler_create. If you give no cadence, Matcha asks; it does not pick one.

/loop tells the scheduler to fire immediately, then repeat. Each fire is a new turn (in this conversation, or in a detached background sub-assistant when [scheduler] background_loops is on — the default). Recurring tasks auto-expire after **7 days**. At most **50** scheduled tasks can be active. Cancel with scheduler_delete using the task id from creation. To change a loop, call scheduler_create again with that id; do not delete and recreate.

Related assistant tools

monitor streams filtered command output as conversation notifications. Keep pipes line-buffered (grep --line-buffered) and filters tight; Matcha can stop a noisy monitor. Stop persistent monitors with kill_command_or_subagent.

Not in this build

Cloud-hosted loops or remote schedulers are not a product surface here. /loop runs against the local scheduler_create tool when the session has it. Cloud Agent (cloud_agent) is disabled.