### Default ### Proactive ### Concise ### Explanatory ### Learning ## Choose between an output style and other features ## Comparisons to related features
The whole hunk
from line 1, old and new numbered
/
lines
from line 1
11# Output styles
22
3> Adapt Claude Code for uses beyond software engineering
3> Change Claude Code's role, tone, and response format with a built-in output style such as Concise or Explanatory, or write a custom style.
44
5Output styles change how Claude responds, not what Claude knows. They set Claude's role, tone, and output format for every response. Use one when you keep re-prompting for the same voice or format every turn, or when you want Claude to act as something other than a software engineer.
5An output style is a set of instructions that sets Claude's role, tone, and response format for every response in a session. Claude Code includes four built-in styles besides its default, and you can write your own.
66
7A custom output style gives Claude your own instructions and lets you choose whether to keep Claude Code's built-in software engineering instructions. Keep them when you're changing how Claude communicates but still coding, like always answering with a diagram. Leave them out when Claude isn't doing software engineering at all, like a writing assistant or data analyst.
7Use an output style to change the way Claude responds and works with you for a whole session, so you don't repeat the request in each prompt. For example, a built-in style can make responses shorter, add an explanation of each change, or have Claude start work without asking routine questions. A custom style can also turn Claude into something other than a software engineer, such as a writing assistant or a data analyst.
88
9For instructions about your project, conventions, or codebase, use [CLAUDE.md](/docs/en/memory) instead.
9* To use a built-in style, pick one from the [built-in output styles](#built-in-output-styles) and [switch to it](#change-your-output-style).
10* To write your own instructions, [create a custom output style](#create-a-custom-output-style).
1011
12<Note>
13 An output style gives Claude instructions to follow. It doesn't guarantee that something always happens or never happens. Some needs fit a different feature:
14
15 * For what Claude should know about your project, use [CLAUDE.md](/docs/en/memory).
16 * For something that has to happen every time, such as formatting after each edit or blocking a command, use a [hook](/docs/en/hooks-guide).
17 * For skills, subagents, and the other options, see [Choose between an output style and other features](#choose-between-an-output-style-and-other-features).
18</Note>
19
1120## Built-in output styles
1221
13Claude Code's **Default** output style is its standard set of instructions, designed to help you complete software engineering tasks efficiently.
22Claude Code starts in the [**Default**](#default) style, its standard instructions for completing software engineering tasks. Each of the four other built-in styles keeps those instructions and adds its own.
1423
15There are four additional built-in output styles:
24This table shows what each style changes about a session and when it fits:
1625
17* **Proactive**: Claude executes immediately, makes reasonable assumptions instead of pausing for routine decisions, and prefers action over planning. This is stronger autonomous-execution guidance than [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) applies, and it works without changing your permission mode, so your permission mode still decides what runs without asking you.
26| Style | What changes | Use it when |
27| :-------------------------- | :-------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- |
28| [Proactive](#proactive) | Claude starts work right away and makes reasonable assumptions rather than asking about routine decisions | You want Claude to keep working through routine decisions, and you'll correct course if an assumption is wrong |
29| [Concise](#concise) | Responses lead with the result and leave out preamble, narration, and recaps | Default responses are longer than you want |
30| [Explanatory](#explanatory) | Claude adds short `Insight` blocks that explain the choices behind the code it writes | You're getting to know a codebase or want the reasoning along with the change |
31| [Learning](#learning) | Claude explains its choices and leaves small pieces of code for you to write yourself | You want hands-on coding practice while the task still gets done |
1832
19* **Concise**: Claude leads with the result, skips preamble and narration, and keeps responses short by default, while doing the engineering work as thoroughly as in the Default style. When you ask for an explanation or more detail, Claude answers in full. Claude always keeps the complete content of error reports, security warnings, and confirmations for destructive actions. Requires Claude Code v2.1.237 or later.
33### Default
2034
21* **Explanatory**: Provides educational "Insights" in between helping you complete software engineering tasks. Helps you understand implementation choices and codebase patterns.
35Default means no output style is selected. Claude Code adds no style instructions, and Claude works from Claude Code's standard system prompt, which is written for software engineering tasks.
2236
23* **Learning**: Collaborative, learn-by-doing mode where Claude will not only share "Insights" while coding, but also ask you to contribute small, strategic pieces of code yourself. Claude Code will add `TODO(human)` markers in your code for you to implement.
37`default` appears in the `/output-style` list with the other styles, so you [select it the same way](#change-your-output-style).
2438
39### Proactive
40
41In the Proactive style, Claude starts implementing as soon as you send a task. It makes reasonable assumptions about routine decisions rather than stopping to ask, and it doesn't switch to plan mode unless you ask for a plan. You can redirect it at any point.
42
43The style's instructions also tell Claude to check with you in the conversation before an action that deletes data or changes a shared or production system. That check is an instruction Claude follows and is separate from permission prompts.
44
45Switching to the Proactive style doesn't change your [permission mode](/docs/en/permission-modes). Your permission mode still decides which tool calls run without asking you, so permission prompts appear the same way they did before you switched.
46
47### Concise
48
49In the Concise style, the first sentence of a response states what happened or what the answer is. Claude leaves out the lead-in, the step-by-step narration, and the closing recap, and answers a simple question in one to three sentences. It does the engineering work as thoroughly as in the Default style. Requires Claude Code v2.1.237 or later.
50
51Claude still writes at full length in these cases:
52
53* **Anything you ask for**: when you ask for an explanation or more detail, Claude answers in full.
54* **Anything you need in order to act safely**: error reports, failing test output, security warnings, and confirmations for destructive actions keep their complete content.
55
56### Explanatory
57
58In the Explanatory style, Claude does the task the way it does in the Default style and adds short explanations of why it made the choices it made. Each explanation appears in the conversation, before or after the code it's about, in a block labeled `Insight`. The explanations aren't written into your files as comments.
59
60An `Insight` block carries two or three points about your codebase or the code Claude wrote, such as this one after adding an API endpoint:
61
62```text theme={null}
63★ Insight ─────────────────────────────────────
64- Every route in this repo goes through the withAuth wrapper, so the new endpoint gets session checks without its own middleware.
65- Rate limits are set per route in limits.ts, which is why this change adds an entry there rather than a global default.
66─────────────────────────────────────────────────
67```
68
69### Learning
70
71In the Learning style, Claude adds the same `Insight` blocks as the [Explanatory style](#explanatory) and also asks you to write some of the code. Claude handles routine implementation itself. When it reaches a piece with a real design decision, such as error handling, a data structure, or business logic with more than one valid approach, it leaves a few lines for you.
72
73Claude marks the spot with a `TODO(human)` comment in the file, then sends a request that says what's already built, what to write, and what to weigh:
74
75```text theme={null}
76● Learn by Doing
77
78Context: The upload form is in place and calls validateFile() before accepting a file. Size and type checks work for images, but the switch statement has no handling for documents yet.
79
80Your Task: In upload.js, implement the case "document" branch inside validateFile(). Look for TODO(human).
81
82Guidance: Decide on a size limit for documents and whether the file extension has to match the MIME type. Return {valid: boolean, error?: string}.
83```
84
85Claude then stops and waits. Write your code at the `TODO(human)` comment and tell Claude when you're done. Claude responds with one `Insight` about your code and continues the task.
86
2587## Change your output style
2688
27Pick a style in one of these ways:
89Pick a style with the command, a menu, or a settings file. The command and both menus save your choice to `.claude/settings.local.json` at the [local project level](/docs/en/settings).
2890
29* **`/output-style` command**: run `/output-style <style>` to switch, for example `/output-style concise`. With no argument, the command lists the styles you can pick and marks the current one. Claude Code saves your selection to `.claude/settings.local.json` at the [local project level](/docs/en/settings).
91* **`/output-style` command**: run `/output-style <style>` to switch, for example `/output-style concise`. With no argument, the command lists the styles you can pick and marks the current one.
3092
3193 The command also works in [non-interactive mode](/docs/en/headless) and Agent SDK sessions, and from the mobile app or web via [Remote Control](/docs/en/remote-control#limitations), where you can list and select only [built-in styles](#built-in-output-styles). Requires Claude Code v2.1.269 or later.
32* **Terminal**: run `/config` and select **Output style** to pick a style from a menu. Claude Code saves your selection to `.claude/settings.local.json` at the [local project level](/docs/en/settings).
33* **VS Code extension**: open the [command menu](/docs/en/vs-code#use-the-prompt-box) with `/` and select **Output styles** to pick a style, including your custom styles. Claude Code saves your selection to `.claude/settings.local.json`, the same file the terminal menu writes. Requires Claude Code v2.1.257 or later.
94* **Terminal menu**: run `/config` and select **Output style** to pick a style from a menu.
95* **VS Code extension**: open the [command menu](/docs/en/vs-code#use-the-prompt-box) with `/` and select **Output styles** to pick a style, including your custom styles. Requires Claude Code v2.1.257 or later.
3496* **Desktop app**: set the `outputStyle` field in a settings file, for example `.claude/settings.local.json`, the file the terminal menu writes. When you run `/config` there, Claude Code [opens **Settings > Claude Code**](/docs/en/desktop#what’s-not-available-in-desktop) rather than a menu.
3597
3698To set a style without the menu, edit the `outputStyle` field directly in a settings file:
from line 103
41103}
42104```
43105
106The value is case-sensitive, so write the built-in names as `Proactive`, `Concise`, `Explanatory`, and `Learning`. A value that doesn't match a style name exactly, such as `explanatory`, gives you the Default style. The `/output-style` command ignores case.
107
108To make a style your default across projects, set `outputStyle` in `~/.claude/settings.json`. A project's own settings files [take precedence](/docs/en/settings#settings-precedence) over that value.
109
44110When you switch styles mid-session, Claude uses the new style starting with your next message. For what that first message costs in prompt caching, see [Changing output style](/docs/en/prompt-caching#changing-output-style). Before v2.1.251, the new style applied only after you ran `/clear` or started a new session.
45111
46112## Create a custom output style
from line 166
100166| `keep-coding-instructions` | No | Set to `true` to keep Claude Code's built-in software engineering instructions alongside your style. Default: `false` |
101167| `force-for-plugin` | No | Plugin output styles only. Set to `true` to apply this style automatically whenever the plugin is enabled, without requiring users to select it. Overrides the user's `outputStyle` setting. If multiple enabled plugins set this, Claude Code uses the first one loaded. Default: `false` |
102168
169<span id="comparisons-to-related-features" />
170
171## Choose between an output style and other features
172
173An output style applies to every response in a session. It's an instruction Claude follows, so nothing enforces it. When what you want is narrower than every response, or has to happen without fail, another feature fits better.
174
175This table matches what you want to the feature that does it:
176
177| You want | Use | Why it fits |
178| :--------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
179| Every response in a certain voice, length, or format, or Claude in a different role | An output style | It applies to the whole session, and you switch styles with one command |
180| Claude to know your project's conventions, commands, and structure | [CLAUDE.md](/docs/en/memory) | It holds what Claude should know about the codebase, and it stays loaded whichever style you pick |
181| Instructions for one kind of task, such as a release checklist or a review procedure | A [skill](/docs/en/skills) | Claude loads it only when you invoke it or the task matches, so it doesn't shape unrelated responses |
182| Something to happen every time without exception, such as formatting after each edit or blocking a command | A [hook](/docs/en/hooks-guide) | Claude Code runs a hook itself at a lifecycle event, so it doesn't depend on Claude following an instruction |
183| A helper with its own instructions, model, and tools for a focused task | A [subagent](/docs/en/sub-agents) | It runs in a separate context with its own system prompt and returns a summary to your conversation |
184| An addition to Claude's instructions that you pass when you start Claude Code | [`--append-system-prompt`](/docs/en/cli-reference#system-prompt-flags) | It appends to the system prompt without removing anything |
185
186These features combine. For example, you can use CLAUDE.md for what Claude should know, an output style for how it responds, and a hook for anything that has to be guaranteed. [Extend Claude Code](/docs/en/features-overview) compares the rest of the extension features.
187
103188## How output styles work
104189
105190An output style changes the instructions Claude Code gives Claude.
106191
107192* Claude Code sends the active style's instructions with every request.
108* When you [select a style other than Default](#change-your-output-style), Claude Code also reminds Claude of the style during the conversation.
109193* Custom output styles leave out Claude Code's built-in software engineering instructions, such as how to scope changes, write comments, and verify work, unless `keep-coding-instructions` is set to `true`.
110194
111195Output styles apply to the main conversation and to a [fork](/docs/en/sub-agents#fork-the-current-conversation), which inherits the parent's full conversation and system prompt. Other [subagents run their own system prompt](/docs/en/sub-agents#what-loads-at-startup), so styles don't change how they respond.
from line 197
113197Token usage depends on the style. A style's instructions add input tokens, though prompt caching reduces this cost after the first request in a session.
114198
115199The built-in Explanatory and Learning styles produce longer responses than Default by design, which increases output tokens. The Concise style does the opposite by instructing Claude to keep responses short by default. For custom styles, output token usage depends on what your instructions tell Claude to produce.
116
117## Comparisons to related features
118
119Several features customize how Claude Code behaves. Output styles change Claude Code's default instructions and apply to every response. The others add instructions without changing the defaults, or scope them to a specific task.
120
121| Feature | How it works | Use it when |
122| :----------------------- | :----------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
123| Output styles | Changes Claude Code's default instructions | You want a different role, tone, or default response format every turn |
124| [CLAUDE.md](/docs/en/memory) | Adds a user message after the system prompt | Claude should always know your project conventions and codebase context |
125| `--append-system-prompt` | Appends to the system prompt without removing anything | You want a one-off addition passed as a [CLI flag](/docs/en/cli-reference#system-prompt-flags) at launch |
126| [Agents](/docs/en/sub-agents) | Runs a subagent with its own system prompt, model, and tools | You want a separately scoped helper for a focused task |
127| [Skills](/docs/en/skills) | Loads task-specific instructions when invoked or relevant | You have a reusable workflow |
128200
129201## Related resources
130202