Output styles in Claude Code: change how Claude responds for the whole session
TL;DR
An output style sets the role, tone and format of Claude Code's responses for a whole session. Concise for speed, Explanatory/Learning for learning; for custom styles, set keep-coding-instructions: true if you still want Claude to code as usual.
Does Claude Code answer at greater length than you want, so you keep asking it to "keep it short"? Or do you want to use it to learn a new codebase, with the reasoning behind each change? Instead of repeating the request in every prompt, an output style sets the role, tone and response format for the whole session. Claude Code ships four styles besides Default, and you can write your own, even turning Claude into a writing assistant or data analyst.
The four built-in styles
| Style | What changes | Use it when |
|---|---|---|
| Proactive | Starts work right away and makes reasonable assumptions on routine decisions instead of asking | You want Claude to keep going and you'll correct course if an assumption is wrong |
| Concise | The first sentence states the result; no preamble, narration or closing recap | Default responses are longer than you want |
| Explanatory | Adds short Insight blocks explaining the reasoning behind the code | You're getting to know a codebase or want the why as well |
| Learning | Like Explanatory, and leaves a few design-decision pieces for you to write (marked TODO(human)) | You want hands-on practice while the task still gets done |
Details worth knowing: Concise still writes in full when you ask for an explanation, and for error reports, security warnings and confirmations of destructive actions. Proactive does not change your permission mode; permission prompts appear as before.
Switching styles
/output-style concise # switch now, case-insensitive
/output-style # list styles, mark the current one
/config → Output style # pick from a menuYour choice is saved to .claude/settings.local.json. To make it the default across projects, put it in ~/.claude/settings.json:
{ "outputStyle": "Explanatory" }Note: in settings files, style names are case-sensitive. Writing explanatory silently falls back to Default.
Writing your own style
A style is a Markdown file in ~/.claude/output-styles (user) or .claude/output-styles (project):
---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---
When explaining code or architecture, start with a Mermaid diagram
(under 15 nodes), then explain in prose.The most important field is keep-coding-instructions. It defaults to false: custom styles drop Claude Code's built-in software engineering instructions (how to scope changes, write comments, verify work). If you only want to change how Claude communicates while it codes the same way, set it to true.
A style or another feature?
| You want | Use |
|---|---|
| Every response in one voice, length or role | Output style |
| Claude to know project conventions, commands, structure | CLAUDE.md |
| A procedure for one kind of task (release checklist) | Skill |
| Something that must happen every time, no exceptions | Hook |
| A helper with its own model and tools | Subagent |
Risks and caveats
- A style is an instruction, not enforcement: Claude tries to follow it but nothing guarantees it. Use hooks for must-haves.
- Token cost: Explanatory and Learning deliberately write more; Concise does the opposite. Switching mid-session affects the prompt cache on the first message.
- Subagents are unaffected: styles apply to the main conversation (and forks); subagents run their own system prompt.
- Editing a style mid-session: restart Claude Code to pick up the change.
How to apply it
- Dev: Use Concise for daily work and switch to Explanatory when entering an unfamiliar codebase.
- Tech Lead: Have juniors use Learning during onboarding week: the work gets done while newcomers write the design-decision parts themselves.
- PM: Write a custom style (with
keep-coding-instructionsleft false) to turn Claude Code into a spec-writing or data-analysis assistant in a docs repo.
Sources & references
- Output styles — Claude Code Docs