| 1 | # Subagent profiles |
| 2 | |
| 3 | Subagent profiles are reusable, explicitly invoked agents for focused work such |
| 4 | as code review, investigation, or documentation. Each profile is a manual Skill |
| 5 | with `runAs: subagent`: Reasonix starts an isolated child agent, gives it the |
| 6 | profile prompt and task, and returns only its final answer to the parent. |
| 7 | |
| 8 | Profiles are shared by the desktop app, interactive CLI, and headless CLI. They |
| 9 | use the existing Skill file format and storage rather than a separate database. |
| 10 | |
| 11 | ## Create a profile |
| 12 | |
| 13 | Create a project profile from a prompt file: |
| 14 | |
| 15 | ```bash |
| 16 | reasonix subagent create reviewer \ |
| 17 | --description "Review changes for correctness and regressions" \ |
| 18 | --prompt-file reviewer.md \ |
| 19 | --tools read_file,grep,bash \ |
| 20 | --model deepseek-pro \ |
| 21 | --effort high |
| 22 | ``` |
| 23 | |
| 24 | With a workspace, `create` defaults to project scope. Outside a workspace it |
| 25 | defaults to global scope. Pass `--scope project` or `--scope global` to make the |
| 26 | choice explicit. Project profiles are stored under |
| 27 | `.reasonix/skills/<name>/SKILL.md`; global profiles are stored under the |
| 28 | Reasonix home Skill directory described in |
| 29 | [Configuration paths](./CONFIG_PATHS.md). |
| 30 | |
| 31 | The prompt may come from `--prompt`, `--prompt-file PATH`, |
| 32 | `--prompt-file -`, or piped stdin: |
| 33 | |
| 34 | ```bash |
| 35 | printf '%s\n' 'Review the task and report only actionable findings.' | \ |
| 36 | reasonix subagent create reviewer --description "Code reviewer" |
| 37 | ``` |
| 38 | |
| 39 | Names may contain letters, digits, `_`, `-`, and `.`. Reasonix refuses a name |
| 40 | that already belongs to another project, global, custom, or built-in Skill. |
| 41 | |
| 42 | ## Invoke a profile |
| 43 | |
| 44 | In an interactive CLI or desktop chat, use a slash command: |
| 45 | |
| 46 | ```text |
| 47 | /reviewer review the current diff |
| 48 | ``` |
| 49 | |
| 50 | This is a real isolated subagent run, not prompt text inserted into the parent |
| 51 | agent. The parent conversation retains the task and the child's final answer, |
| 52 | not the child's full working context. Review and security-review children also |
| 53 | receive a compact parent facts pack (confirmed decisions, evidence summary, file |
| 54 | anchors) and default to 8 steps plus a 2048 output-token cap. |
| 55 | |
| 56 | The parent model can also select a profile at call time without listing profile |
| 57 | names in the tool schema (prompt-cache stability): |
| 58 | |
| 59 | ```text |
| 60 | task(profile="doc-rewriter", prompt="rewrite docs/01.md", write_paths=["docs/01.md"]) |
| 61 | fleet(tasks=[ |
| 62 | {profile="doc-rewriter", prompt="rewrite docs/01.md", write_paths=["docs/01.md"]}, |
| 63 | {profile="doc-rewriter", prompt="rewrite docs/02.md", write_paths=["docs/02.md"]} |
| 64 | ]) |
| 65 | ``` |
| 66 | |
| 67 | - `profile` on `task` / `fleet` items resolves a `runAs: subagent` Skill by name |
| 68 | (explicit names may call `invocation: manual` profiles). |
| 69 | - The profile body becomes the **full** child system prompt — no implicit |
| 70 | concise default is stacked on top. |
| 71 | - `write_paths` declares write targets so parallel writers can share one |
| 72 | workspace. File claims must be disjoint to start together. Directory claims |
| 73 | may start together and only serialize when they realize the same file. |
| 74 | Writer tasks that omit `write_paths` start as a whole-workspace claim |
| 75 | (serializing at start). After path-bound writes only, that reservation |
| 76 | shrinks to the files touched; `bash`/MCP makes it whole-workspace again. In |
| 77 | `fleet`, concurrent omitted claims queue in the scheduler instead of failing |
| 78 | preflight; concurrent directory claims start together. Once a whole-workspace |
| 79 | writer is queued, later writers cannot bypass it. |
| 80 | - Session defaults: `agent.max_subagent_concurrency = 6`, |
| 81 | `agent.max_parallel_writers = 3` (both configurable 1–32; writers ≤ total). |
| 82 | |
| 83 | For scripts and other headless use, choose an explicit command: |
| 84 | |
| 85 | ```bash |
| 86 | # Preview with read-only tools. |
| 87 | reasonix subagent try reviewer "review the current diff" |
| 88 | |
| 89 | # Run with the normal permission and sandbox policy. |
| 90 | reasonix subagent run reviewer "review and fix the current diff" |
| 91 | |
| 92 | # Read the task from stdin and cap tool-call rounds. |
| 93 | git diff | reasonix subagent run reviewer --max-steps 20 |
| 94 | ``` |
| 95 | |
| 96 | Put `run`/`try` flags before the task. Both commands also accept `--model REF` |
| 97 | and `--dir PATH`. `try` always selects the read-only runner. `run` uses the |
| 98 | normal isolated runner; permission `deny` rules and sandbox restrictions still |
| 99 | apply. Ordinary `reasonix run` remains a plain one-shot task entry point and |
| 100 | does not implicitly interpret `/<profile>` syntax. |
| 101 | |
| 102 | ## Manage profiles |
| 103 | |
| 104 | ```text |
| 105 | reasonix subagent list [--dir PATH] |
| 106 | reasonix subagent create <name> --description TEXT (--prompt TEXT | --prompt-file PATH) |
| 107 | [--scope project|global] [--model REF] [--effort LEVEL] |
| 108 | [--tools a,b] [--color NAME] [--dir PATH] |
| 109 | reasonix subagent edit <name> [--description TEXT] |
| 110 | [--prompt TEXT | --prompt-file PATH] [--model REF] [--effort LEVEL] |
| 111 | [--tools a,b] [--color NAME] [--dir PATH] |
| 112 | reasonix subagent delete <name> --yes [--dir PATH] |
| 113 | reasonix subagent try <name> [--model REF] [--max-steps N] [--dir PATH] <task> |
| 114 | reasonix subagent run <name> [--model REF] [--max-steps N] [--dir PATH] <task> |
| 115 | ``` |
| 116 | |
| 117 | `edit` changes only fields supplied on the command line. Use an explicit empty |
| 118 | value to clear an optional field: |
| 119 | |
| 120 | ```bash |
| 121 | reasonix subagent edit reviewer --model= --effort= --tools= --color= |
| 122 | ``` |
| 123 | |
| 124 | An omitted or empty tool list means the profile adds no tool allowlist; the |
| 125 | runner's normal availability, permission, sandbox, and read-only rules still |
| 126 | apply. `delete` requires `--yes` so it is never an implicit destructive action. |
| 127 | |
| 128 | Built-in profiles have no writable Skill file. Their `edit` command accepts |
| 129 | only `--model` and `--effort`, storing the same per-profile overrides used by |
| 130 | desktop settings. Clearing either value removes that override. |
| 131 | |
| 132 | ## File format and advanced profiles |
| 133 | |
| 134 | The CLI and desktop profile editors produce a compact Skill file like this: |
| 135 | |
| 136 | ```yaml |
| 137 | --- |
| 138 | name: reviewer |
| 139 | description: Review changes for correctness and regressions |
| 140 | color: orange |
| 141 | invocation: manual |
| 142 | runAs: subagent |
| 143 | model: deepseek-pro |
| 144 | effort: high |
| 145 | read-only: true |
| 146 | allowed-tools: [read_file, grep, bash] |
| 147 | --- |
| 148 | You are a focused code reviewer. Inspect the requested changes and return only |
| 149 | actionable findings, ordered by severity. |
| 150 | ``` |
| 151 | |
| 152 | `invocation: manual` prevents automatic discovery in the model's |
| 153 | `session-context` Skills catalog; users can still invoke the profile explicitly. `allowed-tools` is a |
| 154 | profile-level allowlist, not a way to bypass permissions. `read-only: true` |
| 155 | forces the read-only tool registry (writer tools stripped); omitted/`false` |
| 156 | keeps the legacy writable default. |
| 157 | |
| 158 | You may hand-author richer `runAs: subagent` Skills, including custom Skill |
| 159 | paths and extra frontmatter. They can be listed and invoked, but the profile |
| 160 | editors deliberately refuse to edit or delete: |
| 161 | |
| 162 | - profiles outside project/global scope; |
| 163 | - profiles whose `invocation` is not `manual`; |
| 164 | - files with frontmatter the editor does not manage; or |
| 165 | - Skill directories containing `references/` or `scripts/`. |
| 166 | |
| 167 | This prevents a simplified editor from silently discarding advanced Skill |
| 168 | content. Manage those profiles as Skill files instead. |
| 169 | |
| 170 | ## Model and effort selection |
| 171 | |
| 172 | The effective model and effort are selected in this order, from highest to |
| 173 | lowest priority: |
| 174 | |
| 175 | 1. per-profile entries in `agent.subagent_models` and |
| 176 | `agent.subagent_efforts`; |
| 177 | 2. this call's `model` / `effort` arguments on `task` or `fleet`; |
| 178 | 3. the profile's `model` and `effort` frontmatter; |
| 179 | 4. `agent.subagent_model` and `agent.subagent_effort` defaults; |
| 180 | 5. the configured executor/default model and its default effort. |
| 181 | |
| 182 | For example: |
| 183 | |
| 184 | ```toml |
| 185 | [agent] |
| 186 | subagent_model = "deepseek-pro" |
| 187 | subagent_effort = "high" |
| 188 | subagent_models = { reviewer = "deepseek/deepseek-v4-pro" } |
| 189 | subagent_efforts = { reviewer = "max" } |
| 190 | ``` |
| 191 | |
| 192 | The `--model` flag on `subagent run` or `subagent try` selects the default model |
| 193 | used to initialize that headless command; profile-specific configuration still |
| 194 | has its documented precedence. |
| 195 | |
| 196 | ## Desktop and troubleshooting |
| 197 | |
| 198 | Profiles created in desktop settings and with `reasonix subagent create` share |
| 199 | the same files. Refresh or start a new session after changing profiles so an |
| 200 | already-running session reloads the Skill registry. |
| 201 | |
| 202 | If invocation reports an unknown or disabled profile, check |
| 203 | `reasonix subagent list`, the current `--dir`, and `skills.disabled_skills`. If |
| 204 | editing reports that a profile is custom or rich, edit its `SKILL.md` directly |
| 205 | instead of forcing it through the profile editor. Unknown model references and |
| 206 | invalid effort levels are rejected when Reasonix resolves the effective model. |
| 207 |