DevSpace subagents

Subagents are optional. Use your normal tools for routine work; delegate only when a separate worker materially helps through independent context, specialization, or follow-up.

Run the devspace CLI through your shell tool from the project the subagent should work in (the git root of the current directory). Commands print compact XML fragments by default. Read that output directly. Add --json only when a program, not a model, parses the output.

Choose a target

Discover usable targets instead of guessing names:

devspace agents targets

Each line is one of:

• <provider name="codex" .../>: an installed coding agent you can run directly.
• <profile name="..." provider="...">description</profile>: a named role (instructions plus provider) defined in .devspace/agents/ or ~/.devspace/agents/.
• <unavailable name="cursor">reason</unavailable>: a provider that cannot run on this machine, with the reason. Do not use it.
• <disabled>: subagents are switched off in the DevSpace config; tell the user instead of retrying.

Pass the name as <profile-or-provider>. Prefer a matching profile; otherwise use a provider. Keep the default model and effort unless the task needs an override (--model, --effort).

Never guess model names. List the exact --model values (and supported efforts) a provider accepts:

devspace agents models <provider>

Start work

Give the subagent a self-contained brief with the objective, relevant paths, constraints, context it cannot infer, and the expected result. It receives this brief (and its profile instructions), not your conversation.

devspace agents run <profile-or-provider> "<brief>"
devspace agents run <profile-or-provider> --model <model> --effort <effort> "<brief>"