Output Styles
Output styles change how Claude Code communicates — its role, tone, verbosity, and whether it explains its reasoning — by modifying the system prompt directly. They change how Claude responds, not what it knows. Reach for one when you keep re-prompting for the same voice or format every turn.
Why use them
- Match your workflow. Terse and action-first when you're moving fast; explanatory when you're learning.
- Teaching mode. Some styles add educational commentary — great while you're getting to know a codebase or a technique.
- Consistency. Set a preferred style once so every session reads the way you like.
The built-in styles
Claude Code ships with four:
| Style | What it does |
|---|---|
| Default | The standard software-engineering system prompt — efficient, action-first. |
| Proactive | Executes immediately and makes reasonable assumptions instead of pausing for routine decisions. Stronger autonomous-execution guidance than auto mode, but you still see permission prompts before tools run. |
| Explanatory | Adds educational "Insights" between steps, explaining implementation choices and codebase patterns. |
| Learning | Collaborative, learn-by-doing: shares Insights and asks you to write small pieces yourself, leaving [TODO(human)] markers in your code. |
Explanatory and Learning produce longer responses by design, so they cost more output tokens than Default.
How to switch
Run /config and pick a style under Output style. Your choice is saved to .claude/settings.local.json at the project level. To set it without the menu, edit the outputStyle field in any settings file:
{
"outputStyle": "Explanatory"
}
:::warning Changes need a fresh session
The output style is part of the system prompt, which Claude Code reads once at session start. A change takes effect only after /clear or a new session. (The standalone /output-style command was removed in v2.1.91 — use /config or the setting above.)
:::
Create a custom style
A custom style is a Markdown file: frontmatter, then the instructions to append to the system prompt. Save it at the user level (~/.claude/output-styles/) or project level (.claude/output-styles/); the file name becomes the style name unless you set name.
---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---
When explaining code, architecture, or data flow, start with a Mermaid
diagram showing the structure, then explain in prose.
Set keep-coding-instructions: true when you're only changing how Claude communicates but still want it coding normally. Leave it out (the default) when Claude isn't doing software engineering at all — say, a pure writing or data-analysis assistant — so the built-in coding instructions are dropped.
Output styles vs CLAUDE.md vs other levers
- Output style = a system-prompt preset for role, tone, and format — applies to every response.
- CLAUDE.md = persistent project facts and rules (conventions, guardrails), added as a message after the system prompt.
- Custom instructions / response styles = the Claude.ai consumer-app cousin.
:::tip Use the right lever Want Claude to "always run tests before finishing"? That's a CLAUDE.md guardrail, not a style. Want it to "explain each step as you go"? That's an output style. Keep behaviour rules in CLAUDE.md and presentation in styles. :::