Claude Code Statusline Customization

A Claude Code statusline is a configurable line in the Claude Code terminal interface that shows session context, such as the active project, Git branch, environment, model label, or custom script output; for broader product context, see our independent guide to Claude features.

c-ai.chat is not Anthropic and does not operate claude.ai. This page explains the statusline as an independent reference, with links to official Anthropic sources where exact behavior matters.

• The short answer
• How it works
• What you would use it for
• How it compares with alternatives
• The practical verdict
• FAQ
• Sources

The short answer

The Claude Code statusline is for developers who work in a terminal and want Claude Code to show useful local context without opening another panel. It is not a separate Claude product. It is a customization point inside Claude Code, Anthropic’s terminal-based coding tool, and Anthropic documents Claude Code in the official Claude developer docs.

Useful statusline content includes the current directory, Git branch, dirty working tree indicator, ticket ID, environment name, or a warning that you are inside production infrastructure. Keep it short. A statusline is a prompt-like cue, not a dashboard.

For plan context, Claude has Free at $0, Pro at $20/month or $17/month annual, Max from $100/month, Team Standard at $25/seat/month or $20/seat/month annual, Team Premium at $125/seat/month or $100/seat/month annual, and Enterprise at a $20/seat base plus API rates. See our Claude pricing guide for the full plan comparison.

How it works

Claude Code statusline customization works by letting Claude Code call a command that returns a short string. Claude Code renders that string as the statusline. The command is usually a shell script, Node script, Python script, or small local binary.

The exact configuration surface belongs to Anthropic. Check the official Claude Code documentation before relying on a specific setting name, JSON field, or setup flow. The stable model is simple: configure a statusline command, keep it fast, make it safe to run repeatedly, and print only the information you want visible.

A good statusline script should not call slow external APIs, request secrets, mutate files, or run project commands with side effects. Treat it like a shell prompt component. It should inspect state and print state.

1. Open Claude Code in a project

   Start from the repository where you normally use Claude Code. The statusline is most useful when it reflects local context such as the branch, directory, or environment.

2. Create a small status script

   Write a script such as ~/.claude/statusline.sh. It should print one compact line and exit quickly.

3. Connect it in Claude Code settings

   Use Claude Code’s documented settings mechanism or built-in setup flow to point the statusline at your command.

4. Test static output first

   Start with output such as Claude Code · local. Then add dynamic fields one at a time.

5. Keep sensitive data out

   Do not print tokens, customer names, production passwords, private URLs, or internal incident identifiers unless you are comfortable with that information being visible on screen.

The most common mistake is overbuilding the line. Prefer short labels such as main, dirty, staging, or Opus over long sentences.

If you also build against Claude through the API, keep the distinction clear. Claude Code is the terminal coding tool. The Claude API is the developer interface for your own applications. A statusline can help your local workflow, but it does not configure API requests, model routing, or token budgets.

What you would use it for

The best Claude Code statusline setups solve small, repeated problems. They make the current session safer or easier to understand. They do not replace your terminal prompt, IDE, issue tracker, or observability tools.

Show the repository and Git branch

This is the most useful default. When you have several terminals open, the statusline can confirm that Claude Code is working in the expected repository and branch.

#!/usr/bin/env bash
repo=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || basename "$PWD")
branch=$(git branch --show-current 2>/dev/null || echo "no-git")
dirty=$(git diff --quiet 2>/dev/null || echo " · dirty")

printf "Claude Code · %s · %s%sn" "$repo" "$branch" "$dirty"

The value is not the snippet itself. The value is avoiding mistakes, such as asking Claude Code to edit files while your terminal is on the wrong branch.

Warn when you are in production

If your shell environment includes deployment context, the statusline can display a clear warning. This helps in infrastructure repositories, incident response work, and machines that have both staging and production credentials.

#!/usr/bin/env bash
env_name="${APP_ENV:-local}"

case "$env_name" in
  production|prod)
    printf "Claude Code · PRODUCTION · review every commandn"
    ;;
  staging)
    printf "Claude Code · stagingn"
    ;;
  *)
    printf "Claude Code · localn"
    ;;
esac

This does not block dangerous actions. It only adds visibility. Use proper permissions, separate credentials, code review, and deployment controls.

Display the model or session mode

Some users want the statusline to show which Claude model or mode they are using. That can help when switching between quick edits, larger refactors, and review tasks. If Claude Code passes model metadata to the statusline command in your installed version, parse the documented field. If it does not, use a manual label.

#!/usr/bin/env bash
mode="${CLAUDE_MODE:-coding}"
printf "Claude Code · %s · %sn" "$mode" "$(basename "$PWD")"

Keep this honest. Do not label a session as using a specific model unless the value comes from Claude Code itself or from configuration you control. For official model availability, use Anthropic’s model documentation or our Claude models guide.

Surface the current ticket or task

If your branch names include ticket IDs, the statusline can extract that ID. This keeps the task visible while Claude Code works across files.

#!/usr/bin/env bash
branch=$(git branch --show-current 2>/dev/null)
ticket=$(printf "%s" "$branch" | grep -Eo '[A-Z]+-[0-9]+' | head -n 1)

if [ -n "$ticket" ]; then
  printf "Claude Code · %s · %sn" "$ticket" "$branch"
else
  printf "Claude Code · no ticket · %sn" "${branch:-no-git}"
fi

This is a good statusline use case because it does one thing. It avoids network calls to Jira, Linear, or GitHub. If you need richer issue detail, use your normal project tools.

Debug the command input safely

When configuring a dynamic statusline, first inspect the input Claude Code provides to the command, if your installed version supports structured input. Use a temporary local script, then remove it after testing. Do not commit debug logs.

#!/usr/bin/env bash
cat > /tmp/claude-code-statusline-input.json
printf "Claude Code · debug input capturedn"

This helps you avoid guessing field names. It also shows whether your version of Claude Code provides the data you want. If a field is not present, do not build logic that depends on it.

How it compares with alternatives

A Claude Code statusline is not a replacement for Cursor, GitHub Copilot, Sourcegraph Cody, or an IDE extension. It is a small terminal interface feature. The comparison matters because many users find it while deciding whether Claude Code fits their editor workflow.

Tool or feature	Where it lives	What it is good at	Main trade-off
Claude Code statusline	Claude Code terminal	Showing compact local context while Claude Code works in a repository	Only useful if you already use Claude Code in the terminal
Terminal prompt themes	Your shell	Showing Git, directory, runtime, and environment state across commands	Not specific to Claude Code sessions
Cursor	Editor	AI-assisted editing inside a code editor with file navigation	Less terminal-native if your workflow starts from the shell
GitHub Copilot	Editor, GitHub, and CLI surfaces	Inline completions, chat, and code suggestions across common IDEs	Status and context behavior depends on the host environment
Sourcegraph Cody	Editor and Sourcegraph context	Repository-aware coding help, especially in code search workflows	Most useful when your team already uses Sourcegraph-style code context

The key difference is control. A statusline is a narrow customization surface that you own. You decide what the script prints. IDE assistants usually provide richer UI, file navigation, inline completions, and code review surfaces, but you have less control over the exact status display.

If you live in an IDE, the statusline may not matter. If you use terminal multiplexers, remote shells, containers, or multiple repositories, it can help because it fits the command-line workflow.

For official product access, use claude.ai. For developer documentation and platform behavior, use Anthropic’s platform docs.

The practical verdict

Claude Code statusline customization is useful if you spend real time in Claude Code and need lightweight context in the terminal. The strongest use cases are branch awareness, environment warnings, task labels, and model or mode labels when those values are available.

Keep the setup boring. Print one line. Avoid secrets. Avoid slow network calls. Use official Anthropic documentation for the exact configuration format, and use c-ai.chat as the independent map of how Claude, Claude Code, the API, pricing, and product features fit together. Start with our Claude resources if you want the wider guide.

FAQ

Can a Claude Code statusline run any command?

It can be configured to run a local command according to Claude Code’s supported settings. Use that power carefully. A statusline command should be read-only, fast, and predictable because it may run often during a session.

Does the statusline work in the Claude web app?

No. The statusline is for Claude Code in the terminal. The web product at claude.ai has its own interface and does not use your local shell scripts.

Can I show token usage or cost in the statusline?

Only if Claude Code exposes the needed data to your statusline command or you track it yourself through supported logs or APIs. Do not assume token or cost fields exist. For API pricing, Anthropic lists Claude Opus 4.7 at $5/M input tokens and $25/M output tokens, Claude Sonnet 4.6 at $3/M input tokens and $15/M output tokens, and Claude Haiku 4.5 at $1/M input tokens and $5/M output tokens. Prompt caching gives 90% off cached input, and the Batch API gives 50% off both directions.

Which Claude models are relevant to Claude Code?

Model availability depends on Anthropic’s product settings and your plan. The current lineup includes Opus 4.7 with a 1M context window, Sonnet 4.6 with a 1M context window and 128K max output, and Haiku 4.5 as the fastest and lowest-cost option. Check Anthropic’s model documentation for the official list before standardizing a workflow.

Is a statusline the same as a Claude Code hook?

No. A statusline is mainly for display. Hooks and tool permissions relate to workflow control, command execution, or automation. Check Anthropic’s Claude Code docs before mixing these concepts in a team setup.

Can teams standardize a Claude Code statusline?

Yes, but they should use normal dotfile, device management, or repository setup practices. Keep team scripts portable. Avoid leaking private infrastructure details. Larger teams should also review Anthropic’s trust and admin materials at trust.anthropic.com.

What should I check if Claude Code is unavailable?

Check status.claude.com before debugging local configuration. A broken statusline script can cause local confusion, but service availability is a separate issue. For general help, see our Claude FAQ.

Independent guide. Not affiliated with Anthropic. For the official Claude product, visit claude.ai.

Last updated: 2026-05-12