Defining throwaway subagents from the CLI with --agents, tested live

Define a session-only subagent as JSON, no file needed — verified live.

When you don't want to create a file

File-based subagents (`.claude/agents/<name>.md`, covered in another article) are great for persistent roles, but a one-off CI script or a quick experiment doesn't always warrant a new file. `--agents` lets you define a session-only subagent as JSON.

The basic shape

`claude --agents <json>` where each key is a subagent name and the value has `description`/`prompt` at minimum, plus `tools`/`model`/`permissionMode`/`mcpServers`/`hooks`/`maxTurns`/`skills`/`effort` and more (per public docs summaries, fetched 2026-07-29).

A minimal example, verified live

A temporary `reviewer` subagent whose persona always starts its answer with `[NAMING-BOT]`, invoked via the Task tool:

$ claude --agents '{"reviewer": {"description": "...", "prompt": "Always start with [NAMING-BOT]."}}' \
  -p "Ask reviewer about the naming of let x = getUserData();" --allowedTools "Task"

Real output: "## [NAMING-BOT] の結論 ... x は不適切 ..."

vs file-based subagents

`--agents` definitions live only for that session and are never written to disk — good for CI/automation without touching the repo.

Defining several at once

Multiple keys in one `--agents` JSON define several subagents in a single call.

Promoting one to a real file

Copy the same `description`/`prompt` fields into `.claude/agents/<name>.md`'s frontmatter + body once you want it to persist.

FAQ

What can --agents do?

Verified live — a JSON with description/prompt acted as a session-only subagent.

Is it saved to disk?

No, it's session-only.

What fields can I set?

Per public docs: description/prompt/tools/model/permissionMode/mcpServers/hooks/maxTurns/skills/effort, similar to file-based frontmatter.

Can I define several?

Yes, multiple keys in one --agents JSON.

Can I make it permanent later?

Yes — copy the same fields into a .claude/agents/<name>.md file.

Find subagent configs →Learn systematically at School →See the All-Access plan →