SSD Nodes Learn Hosting plans →
Guides Matt ConnorBy Matt Connor

Claude Code output styles explained

An output style edits Claude Code's system prompt, so it shapes every reply. What the built-in styles do to your transcript, and how to write your own.

What an output style is in Claude Code

An output style in Claude Code is a block of instructions that Claude Code adds to what it sends Claude with every request. It changes how Claude answers you: the role it takes and the shape of what it prints. It does not teach Claude anything about your codebase, and it cannot give Claude permission to run anything.

Claude Code ships five built-in styles. Your choice lives in one settings key, outputStyle. On Claude Code v2.1.251 or later, a style you switch in the middle of a session applies from your next message. From v2.1.73 until v2.1.251, the switch was saved and then ignored until you cleared, and that one fact explains most of the confusion you will still find in older guides to this feature.

On a VPS this is more than a cosmetic preference. The transcript is what you read through an SSH (secure shell) link, usually inside a tmux window, so every line Claude narrates is a line you wait for and a line in a scrollback buffer of fixed size.

Where the outputStyle setting lives

Pick a style from the /config menu, under Output style. Claude Code writes your choice to .claude/settings.local.json in the project you are working in.

The /output-style command does the same job from the prompt. Run /output-style concise to switch, or /output-style with no argument to list the styles and see which one is current. It saves to the same .claude/settings.local.json file, ignores case, and also works in non-interactive mode. The command as described here arrived in Claude Code v2.1.269. An older /output-style command existed by v2.0.30 and was deprecated in v2.1.73 in favour of /config, so a build between those two releases may not behave as this page describes. Check what you are running before you follow any guide, this one included. Versions on this page were checked in October 2026.

claude --version

You can also set the key by hand. Four settings files can hold it, and the narrower one wins over the broader one.

  • ~/.claude/settings.json is your user file. It applies in every project on that machine.
  • .claude/settings.json is the project file. It is committed to git, so it applies for everyone who clones the repository.
  • .claude/settings.local.json is the local project file. It is not committed, and it overrides both of the above. This is the file the /config menu and the /output-style command write.
  • Managed settings, deployed by an IT team from a system path such as /etc/claude-code/ on Linux, override everything else.

The value of the key is the style name:

{
  "outputStyle": "Concise"
}

The value is case-sensitive. Write the built-in names as Proactive, Concise, Explanatory and Learning. A value that does not match a style name exactly, such as concise, quietly gives you the Default style.

For one session only, pass the same key on the command line. The --settings flag takes a path or an inline JSON string, and its values override the same keys in your user, project and local settings files for that run. Managed settings still win over it:

claude --settings '{"outputStyle": "Concise"}'

The docs list four ways to pick a style, and only two of them carry a minimum version. The /config menu in the terminal has none. The /output-style command in its current form needs v2.1.269, and the Output styles menu in the VS Code extension needs v2.1.257. In the Desktop app you set the outputStyle field in a settings file instead. The outputStyle key itself has no minimum version, so it is the one to rely on. When a screenshot in any guide stops matching what you see, set the key directly and confirm it with /status, which lists the settings sources in effect.

When a new output style takes effect

On Claude Code v2.1.251 or later, a style you switch mid-session, from the command, the menu or the settings file, applies starting with your next message. You do not need to clear. From v2.1.73 until v2.1.251, the running session kept the style it started with, and the new one loaded only on the next /clear or the next launch.

In the terminal, Claude Code reads style files when it starts, so if you create or edit a custom style file while a session is running, restart Claude Code before you select it. In VS Code v2.1.261 or later, the Build a custom style walkthrough in the Output styles menu creates the file and lists the new style immediately. On a build in that older range, or after restarting for a terminal style file edit, these two commands give you a clean slate and then show what loaded:

/clear
/context

/context prints what is currently occupying the context window, broken down by category, including the system prompt. Run it in a fresh session under each style and the system prompt line is the input side of your comparison. It is also the fastest way to prove a custom style loaded at all. For the wider picture of what fills that window, see how context fills up in a long Claude Code session.

Caching is why the switch works the way it does. The API serves repeat requests from a prompt cache that matches on the start of each request, and the system prompt sits at the very start. Rewriting it mid-conversation would invalidate everything behind it, so the next turn would reprocess your entire history as new input. Builds from v2.1.73 until v2.1.251 avoided that cost by fixing the style at session start. Current builds deliver the new style's instructions as a message in the conversation instead, so the request after a switch still reads the system prompt and the earlier conversation from the cache. Switching styles is cheap either way.

What each built-in output style changes about the transcript

  • Default is Claude Code's normal system prompt, written for software engineering work.
  • Concise leads with the result. It drops the preamble and the play-by-play narration, and keeps answers short until you ask for detail. The engineering work behind them is unchanged. It never shortens an error report or a security warning, and it still asks in full before a destructive action. This style needs Claude Code v2.1.237 or later.
  • Explanatory adds educational "Insights" between the steps of a task, covering why an implementation choice was made and what pattern your codebase already uses. The transcript gets longer by design.
  • Learning goes further. Claude shares those insights and then asks you to write small pieces of the code yourself, marking each spot with a TODO(human) comment in the file.
  • Proactive makes Claude act instead of asking. It makes reasonable assumptions on routine decisions rather than stopping for confirmation.

Read that last one carefully, because it is the one people misread. Proactive is guidance in the system prompt. It changes what Claude attempts. Your permission mode still decides what actually runs without asking you, which is the setting that matters on a server you leave running unattended. That is covered in auto mode and Claude Code's permission modes.

How an output style differs from CLAUDE.md, a hook, and a subagent

These surfaces all feel like telling Claude how to behave, and they work at different layers.

  • An output style is part of the instructions Claude Code sends with every request. It applies to every response in the main conversation.
  • CLAUDE.md is added as a user message after the system prompt. It is where project conventions and codebase facts belong.
  • --append-system-prompt appends text to the system prompt for a single invocation, without removing anything. It is the one-off version of an output style.
  • A hook is a shell command that Claude Code runs itself when an event fires. It is enforced by the harness, so it runs whether or not Claude would have chosen to. See what a Claude Code hook can and cannot do.
  • A subagent runs with its own system prompt and its own tool set.

A short test decides between the first two. Facts about your project go in CLAUDE.md, because Claude needs to know them. Phrasing goes in an output style, because it is about how the answer reads. Anything that must happen every single time, whatever the model decides, is a hook. Which layer each surface sits in is a property of the program running the model rather than of the model itself, and that is why a style can only ever influence while a hook can enforce.

Output styles apply to the main conversation only. A subagent does not inherit your style, because it starts its own conversation with its own system prompt. A fork of the current conversation is the exception, since a fork inherits the parent's system prompt exactly. If a subagent writes in a way you dislike, edit that agent's file rather than your style. A second Claude Code session on the same box follows the same boundary, reading the settings files for itself at startup, so when you pass work to another session running alongside yours its replies come back in whatever style that session loaded, not yours.

How to write your own output style

A custom output style is a markdown file with frontmatter. Save it under your home directory to use it in every project, or inside the repository to keep it with the code. The user directory is ~/.claude/output-styles/ and the project directory is .claude/output-styles/.

mkdir -p ~/.claude/output-styles
cat > ~/.claude/output-styles/terse-ops.md <<'EOF'
---
name: Terse ops
description: Command first, explanation after, for SSH sessions
keep-coding-instructions: true
---

Lead with the command or the file change. Put the explanation after it, in two sentences or fewer.

Do not narrate what you are about to do. Report what you did.

When a command can fail, print the one check that proves it worked and say what a healthy result looks like.
EOF

Start a session and open /config. Your style appears in the Output style list with the description you wrote. If it is missing, the file is not being read: check the path, and restart Claude Code if the session was already running when you saved the file. If it appears under its file name with no description, the frontmatter did not parse, and claude --debug shows the parse error. The file name becomes the style name unless the frontmatter sets name, so this one is called Terse ops and not terse-ops.

Select it, or set the key to that exact name, with the same capitals:

{
  "outputStyle": "Terse ops"
}

One field decides whether your file is an adjustment or a replacement. keep-coding-instructions defaults to false, which means a custom style drops Claude Code's built-in software engineering instructions and runs on your text alone. Those built-in instructions are what tell Claude how to scope a change and how to verify its work. Leave the field out for a writing assistant or a data analyst, where none of that applies. Set it to true for anything that still touches code, or you will wonder why a careful engineer suddenly stopped checking its own work. Only Claude Code's full system prompt carries that section, so on the shorter system prompt the field has no effect. Setting the CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT environment variable to 0 selects the full prompt on any model. If what you are really after is not a different voice but a tighter definition of how much work a task deserves, that belongs with the engineering instructions rather than the style file: the Ponytail skill is a worked example, a single rule that pushes an agent toward the smallest change that works.

description is the line the /config picker shows beside the name. Write it for the moment you are choosing between two of your own styles six months from now.

Why a concise style is different over SSH

On a VPS you read the transcript through layers a local terminal does not have, and each layer charges you for verbosity.

Scrollback is the first. In tmux, each pane keeps a fixed number of lines, set by history-limit, which defaults to 2000. A narrated transcript fills that buffer faster, so the earlier part of your session is evicted sooner and the output you wanted to scroll back to is gone. Raise it if you want the room:

echo 'set -g history-limit 20000' >> ~/.tmux.conf
tmux source-file ~/.tmux.conf

Panes created after that keep 20000 lines each, at the cost of memory per pane. On tmux 3.7 or later, changing history-limit also updates panes already open; older versions apply it only to new panes. If you are still building the session layout, running Claude Code inside tmux on a VPS covers it.

Latency is the second. The response streams into your terminal as it is generated. On a link with a high round-trip time, a long preamble is time you spend watching text land before the answer appears.

Output tokens are the third. Every narrated line is billed as output. Explanatory and Learning are longer by design. Concise is shorter by design, because it instructs Claude to keep responses short by default.

Do not trust a percentage from anyone, this page included. The size of the difference depends on your prompts, your model and the work you ask for, so measure your own before and after. Run the same real task in two fresh sessions, one under Default and one under Concise, then compare. A statusline is the easiest meter, because Claude Code hands your script a JSON object on stdin that already carries the style name, the output tokens of the latest reply and a running cost estimate for the session:

cat > ~/.claude/statusline.sh <<'EOF'
#!/bin/bash
input=$(cat)
style=$(echo "$input" | jq -r '.output_style.name // "default"')
out=$(echo "$input" | jq -r '.context_window.total_output_tokens // 0')
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
echo "style=$style out=$out cost=$cost"
EOF
chmod +x ~/.claude/statusline.sh

Point the statusLine setting at it:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

The bar at the bottom of the session now shows the active style beside the size of the most recent reply and the estimated cost of the session so far. out covers only the latest response, so it shows how long each answer runs. cost accumulates, so the figure at the end of each run is your before and after. Read it before you clear, because the cost resets to $0 when /clear starts a new session, and treat it as an estimate rather than your bill. The script needs jq, the command-line JSON parser, so install it first with sudo apt install -y jq. If the bar stays empty, run the script by hand and pipe some JSON into it, because a statusline that exits non-zero prints nothing and reports nothing. A custom Claude Code statusline lists the rest of the fields in that object. For the billing side rather than the session side, read where Claude Code's tokens actually go and the tools that track Claude Code spend.

How to check which output style is actually loaded

Use these checks instead of guessing.

  • /status lists the settings sources in effect for this session, including whether managed settings from an organisation are in play.
  • /context shows the loaded system prompt as a category in the context window breakdown.
  • claude doctor, run from the shell without starting a session, prints installation and settings diagnostics and reports settings files that are invalid.

When a style does not apply, the cause is almost always one of two things. The first is timing: on a build from v2.1.73 up to v2.1.251 a mid-session switch waits for /clear, and in the terminal a style file you created or edited mid-session waits for a restart. The second is precedence: .claude/settings.local.json overrides .claude/settings.json, and both override ~/.claude/settings.json. Because the /config picker and the /output-style command write to the local file, a style your team committed in .claude/settings.json is quietly overridden on any machine where somebody once used either. /status tells you which files loaded but not which one supplied the key, so open each file it lists and look for outputStyle.

A JSON syntax error has the same symptom and a different fix. claude doctor names the file it could not parse, which is worth running before you go looking for anything more complicated. A value in the wrong case, such as explanatory, is valid JSON and still gives you the Default style, so check the capitals too.

FAQ

Why did the /output-style command stop working?

On a current build it has not. /output-style lists the styles and /output-style concise switches to one. The command has a gap in its history: v2.1.73 deprecated it in favour of /config, and v2.1.269 added the current /output-style [name] form, so on a build between those two it may not work as described here. Run claude --version to see what you have. On any build you can pick the style from /config under Output style, or set the outputStyle key in a settings file. The docs give the key no minimum version, so setting it directly is the instruction worth writing down in your own notes.

I changed my output style and nothing happened. Why?

Check your version first. On Claude Code v2.1.251 or later, a style you switch mid-session applies from your next message. From v2.1.73 until v2.1.251 the change was saved but applied only after /clear or a new session. In the terminal, a custom style file you created or edited during the session needs a restart, because Claude Code reads style files when it starts. If it still does not apply, check that the value matches the style name exactly, capitals included, then run /status to see which settings files loaded, since .claude/settings.local.json overrides .claude/settings.json and both override ~/.claude/settings.json.

Does the Concise output style save money?

It moves output tokens in the direction you expect, because it instructs Claude to keep responses short by default. How much depends on your prompts and your model, so treat any published percentage as a measurement of someone else's work. Measure yours: run /context in a fresh session under each style for the input side, then run the same task under each and compare the output tokens and the estimated cost. Concise never shortens an error report or a security warning, so the parts you most need to read stay whole.

Will an output style change how my subagents write?

No. Output styles apply to the main conversation only, because a subagent starts its own conversation with its own system prompt and its own tool set. A fork of the current conversation is the exception, since a fork inherits the parent's system prompt exactly. To change how a subagent responds, edit that agent's own file.

Can an output style let Claude run commands without asking?

No. An output style is text in the system prompt, so it can only influence what Claude tries to do. The Proactive style makes Claude assume and act rather than pause on routine decisions, and it still cannot approve a command. Your permission mode decides what runs without a prompt, and that is the setting to check before you leave a session running on a server.

Was this article useful?