Subagents and Background Tasks
Updated
RightNow Agent, the terminal coding agent, is paused. Its guides stay online as reference.
Subagents run delegated tasks in child sessions with their own context while the parent conversation continues.
Delegate with spawn_subagent
The spawn_subagent tool starts a child session with a focused prompt, a short description, and an agent type. By default, it runs in the background and returns a subagent ID; set background: false to block until the child finishes.
Give the parent a focused task with the files, context, and result you need. To collect a background child's result, ask the parent to read it with get_ and the subagent ID, or watch the child in the Tasks pane (Ctrl+G).
| Agent type | Use |
|---|---|
| general-purpose | Full-capability work that may read, edit, and execute under its permissions. |
| explore | Read-only file investigation, directory listing, and search. |
| plan | Codebase exploration followed by a structured implementation plan, without file edits or shell commands. |
Spawn reference
| Argument | Behavior |
|---|---|
| prompt | Required. The full task instructions for the child. |
| description | Required. A short task label of 3-5 words. |
| subagent_type | Selects the child type; defaults to general-purpose. |
| background | Runs in the background and returns a subagent ID; defaults to true. |
| capability_mode | Filters tool classes: read-only, read-write, execute, or all. Omitted values use the resolved agent and role configuration. |
| isolation | Requests none for a shared workspace or worktree for edits kept separate until explicitly merged. |
| resume_from | Continues a completed child from the current parent session with the same agent type. Its transcript, tool state, and model carry forward. |
| cwd | Uses an existing directory. Do not combine it with worktree isolation; a resumed child keeps its source directory. |
| model | Selects an available model slug when the user requests one; ignored when resuming a child. |
The requested capability mode is intersected with the agent definition and role limits; it cannot widen their tool access. read-only removes built-in file-edit and shell tools; read-write adds file changes, and execute adds shell commands without file-edit tools. Tools without a classified kind, including MCP tools, are retained by this filter.
Worktree isolation copies the working tree, including uncommitted and untracked files. Files are copy-on-write clones where the file system supports it and full copies elsewhere, such as NTFS on Windows. If the worktree cannot be created, the child runs in the shared workspace. Manage worktrees from Sessions.
MCP inheritance
Children inherit already-connected parent MCP servers by default, including plugin agents. Set mcpInheritance in the agent frontmatter to change that.
| mcpInheritance | Inherited servers |
|---|---|
| all (default) | Every connected parent server. |
| none | No parent servers. |
| named: [server] | Only the named parent servers. |
| except: [server] | All parent servers except the named ones. |
Configuration and limits
Keys live in config.toml; the values shown are the defaults.
| Setting | Effect |
|---|---|
| [subagents] enabled = true | false or RIGHTNOW_SUBAGENTS=0 disables subagents; the interactive TUI honors it only when started with --no-subagents, except in leader mode, where the leader process applies it. |
| [subagents] max_depth = 1 | Only the top-level session spawns; set 2 or more to allow deeper nesting. |
| [subagents] max_concurrent = 32 | Concurrent non-workflow subagents per session; additional spawns queue. |
| [subagents] limit_behavior = "queue" | "fail" rejects excess spawns instead of queuing. |
| [subagents.toggle] <type> = true | false disables that agent type; omitted types remain enabled. |
| [subagents.models] <type> | Maps a type to an available model ID; without one, the child uses the parent model. |
Tasks and todos
| Shortcut | Pane |
|---|---|
| Ctrl+G | Tasks, in fullscreen and inline modes: subagents, background commands, monitors, loops, statuses, elapsed time, and task IDs. In minimal mode, Ctrl+G edits the prompt in an external editor. |
| Ctrl+T | Todos: the current task's separate todo list. |
Background commands
A command launched through run_terminal_command with background: true returns a task ID immediately. Press Ctrl+B to move an already-running foreground command into the background.
| Tool | Purpose |
|---|---|
| get_command_or_subagent_output | Read current output and status, optionally waiting up to a timeout (capped at 10 minutes by default). |
| wait_commands_or_subagents | Wait for any or all of up to 20 task IDs. |
| kill_command_or_subagent | Stop a command, monitor, or subagent, or report that it already exited. |
Monitor and scheduled loops
Real-time events with monitor
The monitor tool runs a long-lived script and turns stdout and stderr output into rate-limited notifications. Blank or suppressed lines do not produce notifications. Filter noisy output and use line-buffered pipes. A monitor ends after timeout_ms (default and maximum 10 hours); persistent: true keeps it for the life of the session until it is killed. 30 seconds of sustained overload also stops it.
Periodic checks with /loop
Intervals use seconds, minutes, hours, or days (60s, 5m, 2h, 1d). The minimum is 60 seconds. A loop fires immediately, expires after 7 days, and is managed through the scheduler tools. By default, each run executes in a detached background subagent; [scheduler] background_loops = false runs it in the conversation instead.
Scheduler tools
| Tool | Arguments and result |
|---|---|
| scheduler_create | Creates a recurring prompt from interval and prompt; returns its ID and readable schedule. |
| scheduler_list | Lists active task IDs, shortened prompts, intervals, and next fire times. |
| scheduler_delete | Pass id to cancel a schedule; use the kill tool for a running command, monitor, or subagent. |
durable,foreground, andfire_immediatelydefault to false. Durable tasks persist across sessions; foreground tasks run in the main conversation.- Pass
task_idto update the interval or prompt of an existing schedule; omitted fields stay unchanged. - One-shot scheduler tasks are rejected:
recurring: falseis not supported. - At most 50 scheduled tasks can be active at once.
Personas
A persona layers tone, output format, task focus, model, reasoning effort, isolation, and declared input or output contracts onto a subagent without changing its agent type.
Open /personas to manage personas, or /config-agents to open the full Agents and Personas modal. Project personas live under .rightnow/personas/*.toml; user personas live under <RIGHTNOW_HOME>/ in the effective product home. RightNow Agent 1.0.5 loads project personas without a folder-trust check, so review a repository's .rightnow/personas/ before running RightNow in it.
If a task cannot start, run rightnow doctor and follow the Troubleshooting guide.