skip to content

Output Styles & Status Line

Output styles swap tone and role in the system prompt, and a status line script turns session JSON into a persistent footer. Asked because a style guides responses but never enforces anything.

part ofClaude Coderead it →
on this pageshow

explore

questions

5

In Claude Code, which built-in output styles ship, what does each one change, and how do you switch between them?

level: juniorimportance: must knowfreq 22%

answer

  1. one default plus four styles
  2. result first versus Insight blocks
  3. TODO(human) for hands-on practice
  4. /output-style, /config, outputStyle
  5. case-sensitive value, next-message switch

basics

~20 s

Claude Code starts in Default and ships four more styles: Proactive acts without routine questions, Concise leads with the result, Explanatory adds Insight blocks, and Learning also leaves TODO(human) code for you. Switch with /output-style, /config or outputStyle.

solid answer

~40 s

Default means no style is selected: Claude works from Claude Code's standard software-engineering system prompt. The other four keep those instructions and add their own. `Proactive` starts work right away and makes reasonable assumptions instead of asking about routine decisions, without changing the permission mode. `Concise` leads with the result and drops preamble, narration and recaps while doing the work as thoroughly. `Explanatory` adds short `Insight` blocks in the conversation explaining its choices, and `Learning` adds those plus a `TODO(human)` marker where you write a few lines yourself. Switch with `/output-style concise` (v2.1.269 or later), the **Output style** entry in `/config`, or the `outputStyle` key in a settings file; the command and the menu save to `.claude/settings.local.json`. Since v2.1.251 a switch applies from your next message, with no `/clear` needed.

go deeper

for a junior

Name the five built-in styles and what each changes, and show one way to switch, such as /output-style concise or the Output style entry in /config.

for a middle

Explain that the four non-default styles keep the engineering instructions and add their own, that the choice lands in .claude/settings.local.json, and why a lowercase outputStyle value silently gives Default.

for a senior

Separate tone from control: Proactive changes how readily Claude acts but not the permission mode, and Concise keeps full error and security output. Know which release made mid-session switches apply from the next message.

for a principal

Decide where a team's default style should live, user file, shared project file or nothing, knowing a developer's local choice outranks the shared one and that styles shape tone, never policy.

## What an output style is An **output style** is a set of instructions that sets Claude's role, tone and response format for every response in a Claude Code session. It saves you repeating "be brief" or "explain your reasoning" in each prompt. It is guidance: Claude follows it, but nothing in Claude Code enforces it. Project knowledge belongs in CLAUDE.md, and anything that must happen every time belongs in a hook. ## The five built-in styles **Default** is the absence of a style: Claude Code adds no style instructions and Claude works from its standard system prompt, written for software engineering. Each of the other four **keeps** those instructions and adds its own. | Style | What changes | Fits when | |---|---|---| | `Default` | Nothing is added | You want the standard engineering behaviour | | `Proactive` | Starts work at once, makes reasonable assumptions about routine decisions, and does not enter plan mode unless you ask for a plan | You will correct course if an assumption is wrong | | `Concise` | The first sentence states the result; no lead-in, step-by-step narration or closing recap; simple questions get one to three sentences | Default answers are longer than you want | | `Explanatory` | Adds short `Insight` blocks in the conversation explaining the choices behind the code | You are learning a codebase | | `Learning` | Adds `Insight` blocks and leaves a `TODO(human)` marker where a real design decision sits, then waits for you | New team members want hands-on practice | Some details interviewers probe: - **Concise does not cut engineering work.** It shortens prose only, and still writes in full when you ask for detail or when you need it to act safely: error reports, failing test output, security warnings and confirmations for destructive actions keep their complete content. It requires v2.1.237 or later. - **Explanatory writes nothing into your files.** The `Insight` blocks appear in the conversation, before or after the code they discuss. Learning is the style that edits files for teaching: it inserts the `TODO(human)` comment and asks you to fill it in. - **Proactive does not change the permission mode.** Your permission mode still decides which tool calls run without asking. The style's instruction to check with you before deleting data or touching shared or production systems is something Claude follows in conversation, separate from permission prompts. - **Token use differs.** Explanatory and Learning produce longer responses by design; Concise produces shorter ones. ## Switching styles 1. Run `/output-style <style>`, for example `/output-style concise`. With no argument it lists the styles and marks the current one. The command ignores case. 2. Or run `/config` and pick **Output style** from the menu. 3. Or set `outputStyle` in a settings file, such as `{"outputStyle": "Explanatory"}`. The command and the menu both save your choice to `.claude/settings.local.json`, the local project file. To make a style your default everywhere, set `outputStyle` in `~/.claude/settings.json`; a project's own settings files take precedence over it. ## Traps - **The settings value is case-sensitive.** Built-in names are written `Proactive`, `Concise`, `Explanatory` and `Learning`. A value that does not match a style name exactly, such as `explanatory`, gives you Default without an error, which is why a style that works from `/output-style` can silently fail from a hand-edited file. - **Mid-session switches apply from the next message.** Since v2.1.251 Claude uses the new style starting with your next message; before that release the new style applied only after `/clear` or a new session. - **Scripted and desktop use.** Since v2.1.269 `/output-style` also works in non-interactive runs and Agent SDK sessions. In the desktop app, `/config` opens the settings screen rather than a menu, so set `outputStyle` in a settings file there. - **Colour is a separate setting.** `/theme` changes the colour theme, including custom themes stored as JSON in `~/.claude/themes/`; it has no effect on how Claude writes. ## Release history worth knowing Anyone who learned output styles a few months earlier may remember a different command surface. In v2.1.73 the `/output-style` command was deprecated in favour of `/config`, and the style was fixed at session start. In v2.1.269 `/output-style [name]` returned to list and switch styles, including in non-interactive sessions and over Remote Control, where only built-in styles can be picked. Answers here assume v2.1.286.

  • You set "outputStyle": "concise" in .claude/settings.json and nothing changed, although /output-style concise worked earlier. Why?
    The settings value is case-sensitive while the `/output-style` command ignores case. `concise` does not match the style name `Concise` exactly, so Claude Code falls back to Default without an error. Write `"Concise"`. Also check `.claude/settings.local.json`: the command and the `/config` menu write there, and that local file outranks the shared project file.
  • Does the Proactive style mean Claude stops asking for permission before running commands?
    No. Proactive changes how Claude works, starting at once and assuming routine decisions, but it leaves the permission mode untouched, so permission prompts appear exactly as before. Its instruction to check with you before deleting data or changing a shared or production system is a conversational check Claude follows, not a permission prompt. Fewer prompts is a permission-mode decision, not a style one.
  • Which built-in style changes your files as part of its teaching, and how?
    Learning. When Claude reaches a piece with a real design decision, it writes a `TODO(human)` comment at that spot, sends a request saying what is built, what to write and what to weigh, then stops and waits. After you write the code and tell it you are done, it replies with an `Insight` about your code and continues. Explanatory never writes its explanations into files.

  • Proactive turns off permission prompts the way a permission mode would.
  • Concise does less thorough engineering work to keep answers short.
  • Explanatory writes its explanations into the code as comments.
  • outputStyle accepts any capitalisation, such as explanatory in lowercase.
  • Switching style mid-session still needs /clear or a restart.
  • /output-style is gone for good; only /config can switch styles.

Assumes Claude Code 2.1.286; /output-style <name> returned in 2.1.269, mid-session switches apply from the next message since 2.1.251, and Concise needs 2.1.237.

open as a page

In Claude Code, how does an output style differ from CLAUDE.md, --append-system-prompt and a hook, and why can it never enforce a rule?

level: seniorimportance: must knowfreq 14%

basics

~20 s

An output style reshapes how Claude responds: built-ins add instructions, custom styles also drop the coding instructions unless kept. CLAUDE.md and --append-system-prompt only add. All three are guidance; enforcement comes from hooks and permission rules.

open as a page

How do you write and share a custom Claude Code output style, and what does its keep-coding-instructions field control?

level: middleimportance: should knowfreq 10%

basics

~10 s

A custom style is a Markdown file in ~/.claude/output-styles or a project's .claude/output-styles, with name, description and keep-coding-instructions frontmatter. Unless keep-coding-instructions is true, Claude Code leaves out its built-in software-engineering instructions.

open as a page

How does a Claude Code statusLine command receive session data, and how would you script a footer showing the git branch and context use?

level: middleimportance: should knowfreq 12%

basics

~20 s

Claude Code runs the statusLine command from settings with session JSON on stdin and shows whatever it prints to stdout. A script reads workspace.current_dir and context_window.used_percentage, asks git for the branch, and echoes one line.

open as a page

A Claude Code status line goes blank, or shows a stale git branch while background subagents work: what decides when the statusLine command runs, and how do you fix each?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

The statusLine command runs at session start and on events such as a new assistant message, /compact, or a permission-mode change, debounced 300ms. Idle sessions fire none, so set refreshInterval; blank means a non-zero exit, empty stdout or an untrusted folder.

open as a page