Claude Code output styles explained

What an output style is in Claude Code

An output style in Claude Code is a block of instructions that Claude Code appends to its system prompt. 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, and that key is read once when the session starts. That single fact explains most of the confusion around this feature, because a style you switch in the middle of a session is saved and then ignored until you clear.

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 standalone /output-style command no longer exists. It was deprecated in v2.1.73 and removed in v2.1.91, so on a current build it does nothing at all. Check what you are running before you follow any older guide. Versions on this page were checked in August 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 writes.
• 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"
}

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 the settings files for that run:

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

Menu labels and slash commands have both changed at least once in this feature's life. The outputStyle key has not. 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.

Why your new output style does nothing until you clear

Claude Code builds the system prompt once, when the session starts, and the output style is part of that system prompt. So changing the setting while a session runs stores the value and changes nothing you can see, because the running session keeps sending the prompt it built at startup. The new style loads on the next /clear or the next launch.

/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.

There is a reason the setting waits instead of applying live. 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. Fixing the style at session start avoids that cost. Switching styles is cheap. It just needs a clear.

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 added to the system prompt. 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.

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.

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 check that the --- frontmatter block is the first thing in the file. 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 and clear:

{
  "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.

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. Panes already open keep the old limit, because the buffer size is fixed when the pane is created. 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 both the style name and the token counts:

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 tokens it has produced, which is exactly the before and after you need. 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 that you changed it mid-session, so run /clear. The second is precedence: .claude/settings.local.json overrides .claude/settings.json, and both override ~/.claude/settings.json. Because the /config picker writes to the local file, a style your team committed in .claude/settings.json is quietly overridden on any machine where somebody once used the menu. /status is what tells you which source won.

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.

FAQ

Why did the /output-style command stop working?

It was deprecated in v2.1.73 and removed in v2.1.91, so on a build from mid-2026 the command no longer exists. Run claude --version to see what you have. Pick the style from /config under Output style, or set the outputStyle key in a settings file. The key has outlived the command, so setting it directly is the instruction worth writing down in your own notes.

I changed my output style and nothing happened. Why?

The output style is part of the system prompt, and Claude Code builds the system prompt once when the session starts. A change made mid-session is saved but not applied, because the running session keeps sending the prompt it built at startup. Run /clear or start a new session. If it still does not apply, run /status to see which settings source won, 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 token count. 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.