Subagents

Run bounded built-in, custom, and external agents without inheriting hidden conversation state.

View Markdown

Inspect available agents

Open /subagents to inspect built-in definitions and manage custom profiles. The list shows each profile’s execution kind, model role, scope, tools, and delegation grants.

The public built-in IDs are:

builtin/scout
builtin/griller
builtin/planner
builtin/executor
builtin/reviewer
builtin/coder
builtin/web-search
builtin/web-tester

Run one request

Pass the complete task context in the request. A child does not automatically inherit the parent conversation.

text

/subagent builtin/scout explain the cancellation path in app/model.go

Custom profiles use their bare name in the TUI. Delegation grants stored inside profiles use canonical IDs such as builtin/scout, global/code-reader, or workspace/browser-check.

Define an inner agent

Inner profiles select a q model role, an explicit tool list, and directly callable delegates.

yaml

version: 1
name: code-reader
description: Explain the requested code.
kind: inner
role: scout
system_prompt: |
  Read the requested code and explain its behavior with concrete file references.
tools:
  - list_directory
  - read_file
delegates:
  - builtin/scout

Profiles live in ~/.q/subagents/ or <workspace>/.q/subagents/. A workspace profile replaces the complete global profile with the same name.

External agents

External profiles bind to an enabled ACP connection. They store a system prompt and whether the remote agent may mutate the workspace; they do not select q tools, delegates, or a q model role.

Because ACP session creation has no system-message field, q prepends the stored system prompt to the first ordinary ACP prompt. Missing or disabled connections make the profile unavailable without deleting it.