Output styles and the status line

Two things that shape your Claude Code experience quietly but constantly: output style determines how Claude responds to each of your requests, while the status line shows session state in real time. Both are personal settings that don't touch agent logic and don't consume extra API tokens.

Output styles: agent behavior style

An output style is a set of instructions added to Claude Code's system prompt. Not to your messages — to the system prompt, which is read once when the session starts. This means a style change only takes effect after /clear or in a new session.

Built-in styles

Four styles are available out of the box:

Note: Proactive is not the same as bypassPermissions. The permission mode does not change — only the agent's behavior changes (fewer clarifying questions, more initiative).

How to switch styles

The easiest way is via /config, under Output style. Claude Code will show a menu, and the selection is saved to .claude/settings.local.json at the project level.

Manually — add the outputStyle field to any settings file:

{
  "outputStyle": "Explanatory"
}

The settings hierarchy is standard: enterprise → user → project → local. If settings.local.json has Proactive and the enterprise settings have Default, local wins.

Custom output style

When none of the built-in styles fit — create your own. It's a Markdown file with frontmatter. The filename becomes the style name unless a name is specified in the frontmatter.

File locations:

• User level: ~/.claude/output-styles/
• Project level: .claude/output-styles/
• Inside a plugin: output-styles/ in the plugin root

Example — a style that requires every explanation to begin with a diagram, but leaves all engineering logic untouched:

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


::widget{id="rc-3"}


::widget{id="rc-2"}


::widget{id="rc-1"}

## Diagram conventions

Use `flowchart TD` for control flow and `sequenceDiagram` for request paths.
Keep diagrams under 15 nodes.

The key frontmatter field is keep-coding-instructions:

• true — Claude Code keeps its built-in development instructions (how to copy changes, how to write comments, how to verify work). Use this when you're changing the format of responses but still coding.
• false (default) — built-in instructions are removed. Suitable when Claude is acting as a data analyst, technical writer, or any other non-development role.

Full list of frontmatter fields:

Use force-for-plugin with care: if multiple loaded plugins set it to true, Claude Code takes the first one loaded and ignores the rest.

Output style vs. CLAUDE.md vs. Skills

A common question: what goes where?

Output style  → "How Claude responds to every request" (role, tone, format)
CLAUDE.md     → "What Claude knows about the project" (conventions, commands, architecture)
Skill         → "What Claude can do for a specific task" (portable expertise)

If you want Claude to always respond in English and in code-review style — that's an output style. If you need it to know that tests are run with pnpm test --coverage — that's CLAUDE.md. If you need a reusable deployment procedure — that's a skill.

The status line

The status line is the bar at the bottom of the Claude Code interface. By default it shows a minimal set: model, permission mode. But the bar is fully customizable: Claude Code runs your shell script, pipes session JSON data to it via stdin, and whatever the script writes to stdout becomes the status line.

Important: the status line runs locally and does not consume API tokens.

Quick start: /statusline

The easiest way is to describe what you want in /statusline using natural language:

/statusline show model name and context percentage with a progress bar

Claude Code will generate a script in ~/.claude/ and immediately register it in settings.json. This is a convenient starting point.

Manual configuration

For full control — add a statusLine block to ~/.claude/settings.json (or the project-level .claude/settings.json):

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2,
    "refreshInterval": 30
  }
}

Fields:

• command — path to a script or an inline command (e.g., via jq).
• padding — extra horizontal spacing.
• refreshInterval — re-run the script every N seconds in addition to event-driven updates. Useful when the status line shows a clock or subagent status while the main session is idle.
• hideVimModeIndicator — hide the built-in -- INSERT -- indicator if you render vim.mode yourself.

The line updates after every assistant response, after /compact, when the permission mode changes, and when vim mode is toggled. Updates are debounced with a 300 ms delay.

Data available to the script

Claude Code passes a JSON object with the full session state to stdin. Key fields:

{
  "model": { "id": "claude-opus-4-8", "display_name": "Opus" },
  "workspace": {
    "current_dir": "/home/user/project",
    "git_worktree": "feature-xyz",
    "repo": { "host": "github.com", "owner": "acme", "name": "backend" }
  },
  "context_window": {
    "used_percentage": 42,
    "remaining_percentage": 58,
    "context_window_size": 200000
  },
  "cost": {
    "total_cost_usd": 0.0124,
    "total_duration_ms": 145000,
    "total_lines_added": 87
  },
  "rate_limits": {
    "five_hour": { "used_percentage": 31.5 },
    "seven_day": { "used_percentage": 18.2 }
  },
  "effort": { "level": "high" },
  "vim": { "mode": "NORMAL" },
  "pr": { "number": 42, "url": "https://github.com/...", "review_state": "pending" },
  "output_style": { "name": "Explanatory" },
  "session_name": "refactor-auth",
  "version": "2.1.153"
}

The rate_limits fields are only available to Claude.ai subscribers (Pro/Max). The vim, agent, pr, worktree, and session_name fields are only present when the corresponding features are active — always provide a fallback via // empty or or 0.

Terminal size is available through the COLUMNS and LINES environment variables (Claude Code v2.1.153+). The standard tput cols does not work inside the script — the script runs without direct terminal access.

Practical example: color-coded context indicator

#!/bin/bash
input=$(cat)

MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')

# Color based on fill threshold
if [ "$PCT" -ge 90 ]; then COLOR='\033[31m'   # red
elif [ "$PCT" -ge 70 ]; then COLOR='\033[33m' # yellow
else COLOR='\033[32m'; fi                      # green
RESET='\033[0m'

# Progress bar with 10 blocks
FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))
printf -v FILL "%${FILLED}s"; printf -v PAD "%${EMPTY}s"
BAR="${FILL// /▓}${PAD// /░}"

COST_FMT=$(printf '$%.3f' "$COST")

echo -e "[${MODEL}] ${COLOR}${BAR}${RESET} ${PCT}% | 💰 ${COST_FMT}"

Save to ~/.claude/statusline.sh, make it executable (chmod +x), and register it in settings.json.

Multi-line status bar

Each echo becomes a separate line in the status area. This lets you build a compact "dashboard":

# Line 1: model + directory + git branch
BRANCH=$(git branch --show-current 2>/dev/null)
echo -e "[${MODEL}] 📁 ${DIR##*/} | 🌿 ${BRANCH}"

# Line 2: context + cost
echo -e "${COLOR}${BAR}${RESET} ${PCT}% | 💰 ${COST_FMT}"

subagentStatusLine

There is one more settings field — subagentStatusLine. It configures not the bottom bar of the interface, but the per-agent lines in the agent panel:

{
  "subagentStatusLine": {
    "type": "command",
    "command": "~/.claude/subagent-statusline.sh"
  }
}

The script receives a JSON object on stdin with a tasks array — each subagent has fields id, name, status, description, and timestamps. The output replaces the default name · description · token count line for each agent. Useful when several background agents are running and you need to distinguish them by something more meaningful than a default name.

Ecosystem: ready-made solutions

If you'd rather not write a script from scratch, several ready-made themes and generators are already available in open source:

• ccstatusline (GitHub: sirmalloc/ccstatusline) — Powerline-compatible themes, configured via a config file.
• claude-statusline (felipeelias, Go) — a self-contained binary with ready-made widgets.
• Starship integrations — if you already use Starship in your terminal, some metrics can be piped there.

Keep in mind: any third-party script has full access to the session JSON data, including cost and rate limits. Review the code before using it.

See also

• CLAUDE.md and the memory system — use CLAUDE.md for project context, not output styles
• Settings and configuration hierarchy — the outputStyle and statusLine fields follow the standard settings.json hierarchy
• Subagents and context isolation — subagentStatusLine configures how subagents are displayed in the agent panel
• Plugins and marketplace — plugins can ship output styles via the output-styles/ directory and activate them with force-for-plugin
• Skills — portable expertise — an alternative to output styles for tasks that require portable expertise rather than a persistent response style
• Managing the context window — context_window.used_percentage in the status line helps you track context usage
• Choosing a model and thinking modes — the model.display_name and effort.level fields are available in the status line
• Choosing between a command, skill, subagent, MCP, or hook — a decision matrix that includes output styles as a distinct customization mechanism