• A Claude Code status line is a script you configure. It receives session data as JSON on stdin and prints a row above the footer. The docs say it runs locally and does not consume API tokens.
• Set it up with the /statusline command, or add a statusLine entry with type command to settings.json.
• The JSON includes context-window percentage, estimated session cost, 5-hour and 7-day plan usage (Pro and Max only) and prompt cache health (v2.1.251 or later).
• Guard every optional field, keep the script fast, and cache slow git calls by session_id. A non-zero exit or empty output blanks the line.
• Session cost is a client-side estimate at list price. On Pro and Max it is not relevant for billing, so use it as a guide.

A Claude Code status line is a row in the terminal that runs a script you choose and shows whatever the script prints. Claude Code passes the script session data as JSON, so you can keep context fill, session cost, plan limits and git state in view without typing a command. Per the docs, it runs locally and does not consume API tokens.

This guide covers setup, the fields worth showing, a working script, and the mistakes that leave the line blank or stale. It is based on the official status line and cost documentation.

What is the Claude Code status line?

The status line renders in its own row above the built-in footer badges. It does not replace them, but once a custom status line is configured, Claude Code stops showing most of the footer's keyboard hints, including esc to interrupt.

Your script reads JSON on stdin and writes text to stdout. Each line you print becomes a row. You can use ANSI colors, and OSC 8 escape sequences for clickable links in terminals that support them (iTerm2, Kitty, WezTerm).

Three reasons to use one:

• Context fill. You see how full the window is before a compaction fires.
• Which session is which. With several sessions open, the line can show the branch, worktree or session name.
• Limits and spend. Plan usage and cost sit next to your prompt instead of behind a command.

How do I set up a status line?

There are two routes.

Option 1: let Claude write it

Run /statusline with a plain-language request. Claude Code generates a script in ~/.claude/ and updates your settings:

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

Approve the file edit prompts if Claude Code asks for permission.

Option 2: configure it by hand

Add a statusLine field to ~/.claude/settings.json (user settings) or to project settings. Set type to "command" and point command at a script:

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

The command runs in a shell, so an inline command works too. This one uses jq to print the model and context percentage:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

There is also a refreshInterval setting that re-runs the command on a fixed timer. You need it for clocks, or when the line depends on something that changes while the main session is idle.

A minimal working script

Save this as ~/.claude/statusline.sh:

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

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

echo "[$MODEL] ${DIR##*/} | ${PCT}% context"

Then run chmod +x ~/.claude/statusline.sh. Claude Code reloads settings automatically and runs the script as soon as you save the settings file.

To test without starting a session, pipe in mock input:

echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ~/.claude/statusline.sh

What data can the status line show?

The JSON is larger than most people expect. These fields are the most useful day to day:

Two details matter for accuracy:

• used_percentage is calculated from input tokens only (input_tokens + cache_creation_input_tokens + cache_read_input_tokens). Output tokens are not included. /context can read higher because it adds an estimate for messages added since the last API response.
• cost.total_cost_usd is computed locally from token counts at list price, unless an administrator has set a modelPricing table in managed settings. The cost docs call it an estimate. They also say that on Pro and Max the session cost figure is not relevant for billing, because usage is included in the subscription. The total resets to $0 when /clear starts a new session.

Plan limits only appear for some accounts

rate_limits is present only for claude.ai Pro and Max subscribers (or behind a Claude apps gateway with a spend limit), and only after the first API response in a session. Each window can be absent on its own, and Claude Code drops a window once its resets_at time passes. A script that assumes the field exists will misbehave on API-key setups.

Cache health

The prompt_cache object needs Claude Code v2.1.251 or later and appears after the main conversation's first API response. It includes warm, ttl ("5m" or "1h"), expires_at, hit_ratio (0 to 1) and misses. From v2.1.260 it also reports a likely cause for the last miss, such as tools_changed, system_prompt_changed or ttl_expired_5m. The same statistics appear on the Prompt cache (main) line of /usage. Subagent requests are not counted.

A miss means a request re-processed content the cache already held. In the docs' definition, that is more than 5% and at least 2,000 tokens of what could have been read from cache, with no compaction or tool-result clearing to explain it.

A status line for context, cost and limits

This script puts a colored context bar, cost and plan usage on one row, and copes with absent fields:

#!/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')
FIVE_H=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
WEEK=$(echo "$input" | jq -r '.rate_limits.seven_day.used_percentage // empty')

GREEN='\033[32m'; YELLOW='\033[33m'; RED='\033[31m'; RESET='\033[0m'
if [ "$PCT" -ge 90 ]; then C="$RED"
elif [ "$PCT" -ge 70 ]; then C="$YELLOW"
else C="$GREEN"; fi

FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))
printf -v FILL "%${FILLED}s"; printf -v PAD "%${EMPTY}s"
BAR="${FILL// /#}${PAD// /-}"

LIMITS=""
[ -n "$FIVE_H" ] && LIMITS=" | 5h $(printf '%.0f' "$FIVE_H")%"
[ -n "$WEEK" ] && LIMITS="$LIMITS 7d $(printf '%.0f' "$WEEK")%"

echo -e "[$MODEL] ${C}${BAR}${RESET} ${PCT}% | $(printf '$%.2f' "$COST")${LIMITS}"

The color thresholds (green under 70%, yellow 70 to 89%, red from 90%) match the docs' multi-line example; adjust them to taste. The // empty idiom prints nothing when a field is missing, so the limits segment disappears for accounts without rate_limits.

How often does the status line run?

It runs once when a session starts or resumes, then again when:

• a new assistant message arrives
• /compact finishes
• the permission mode changes
• vim mode toggles
• the command in your settings changes
• a refreshInterval timer elapses, if you set one
• a rate-limit window reaches its resets_at time, or a warm prompt cache reaches its expires_at time

Updates are debounced at 300 ms, except that a change to the command itself runs right away. If a new update triggers while your script is still running, Claude Code cancels the in-flight run. The event-driven triggers can go quiet when the main session is idle, for example while a coordinator waits on background subagents. Set refreshInterval if the line must stay current then.

Common problems and fixes

The line is blank. Check these in turn:

• The script is not executable (chmod +x).
• It writes to stderr instead of stdout.
• It exits non-zero or prints nothing. Claude Code displays output only after the script exits with code 0.
• You have not accepted the workspace trust dialog for the folder. Until then the line stays blank, and claude --debug logs Status line command skipped: workspace trust not accepted.
• disableAllHooks is true outside managed settings, in which case only a statusLine from managed settings runs. Or your organization sets allowManagedHooksOnly, which means you can only get a status line from managed settings.

claude --debug logs your script's stderr on every invocation and its exit code on the first one in a session, which makes it the quickest way to find a parse error.

Values show -- or empty. Fields can be null before the first API response. context_window.used_percentage may be null early in a session, and context_window.current_usage is null again right after /compact until the next API call. Use fallbacks such as // 0.

The line lags. The script runs often, and git status or git diff in a large repo is slow. Cache the result in a temp file for a few seconds. Key the cache on session_id from the JSON, not on $$: a process ID changes on every invocation and defeats the cache, while session_id is stable within a session and unique across concurrent ones. The docs include a full example that refreshes git info every 5 seconds.

Links are not clickable. Terminal.app does not support them. If your terminal does but the link text is not clickable, Claude Code may not have detected hyperlink support; launch with FORCE_HYPERLINK=1 claude. SSH and tmux can strip the escape sequences. If escape codes show up as literal text, use printf '%b' instead of echo -e.

Windows paths. With Git Bash, write paths in command with forward slashes. Unquoted backslashes are treated as escape characters, and the command fails without a visible error.

Garbled output. Complex escape sequences, especially in multi-line status lines, can occasionally corrupt the display. Simplify to plain text if you see it.

Status lines for subagents

A separate subagentStatusLine setting customizes the row shown for each subagent in the agent panel. Its command runs once per refresh tick and receives all visible rows as one JSON object, with a tasks array whose entries include fields such as name, status, model, tokenCount and contextWindowSize. You answer with one JSON line per row, in the form {"id": "<task id>", "content": "<row body>"}. Omit id to keep the default row; send an empty content to hide it. The same trust, disableAllHooks and allowManagedHooksOnly gates apply as for statusLine. If you split work across helpers, this is a cheap way to see which one is using the most tokens.

Should the status line be shared with a team?

Because statusLine executes a shell command, it falls under the same workspace-trust rule as hooks in settings files. A project-level status line therefore runs code from the repository on whoever trusts the folder. Keep shared scripts small and reviewable, and prefer user settings for personal preferences. Plugins can ship a default subagentStatusLine, but unlike hooks, those values do not run under allowManagedHooksOnly.

Conclusion

A status line is a small script that keeps context fill, estimated cost and plan usage in front of you, so you can compact or start fresh before a session gets expensive. Start with /statusline, move to a hand-written script once you know which fields you read, guard every optional field, and cache anything slow. Treat the cost figure as an estimate; for authoritative billing, the cost docs point to the Usage page in the Claude Console.

Sources

• Customize your status line - Claude Code Docs
• Manage costs effectively - Claude Code Docs

Originally published on the Atlas blog.

• Claude Pro and Max plans have a five-hour session limit and a weekly limit, and Claude chat and Claude Code draw from the same allowance.
• At the limit the agent stops, or may be allowed to finish its current step. Files already changed stay changed; you wait for the reset, upgrade, or turn on usage credits.
• Long conversations, bigger models, higher effort and many connected tools use the allowance faster, so short, focused sessions stretch it further.
• Several AI engineers working at once use the plan faster, so size the plan to the amount of parallel work.
• Usage credits and API credits are billed at standard API rates, outside the plan price, so decide who may turn them on before you hit the wall.

If your AI coding agent suddenly stops and says a limit has been reached, you have not broken anything. On Claude Pro and Max plans, Claude Code runs against a usage allowance, and that allowance has two main parts: a limit for each five-hour session and a limit for each week. When you reach one, the agent stops until it resets, or until you pay for more.

This guide explains those limits in plain English, what uses them up, and how a founder, product owner or manager can plan around them.

What are AI coding agent usage limits?

Think of a mobile data plan, but with two meters instead of one. Anthropic's help pages say that both Pro and Max have a five-hour session limit and a weekly limit. Max plans also have a separate weekly limit for Fable, which sits apart from the general weekly limit.

Paid plans have a session limit that resets every five hours and weekly limits that reset once a week. Anthropic's help pages give no exact message counts or token numbers, so nobody can tell you in advance "you get exactly this many tasks." What you can learn is how fast your own work uses the meters. (A "token" is a small chunk of text the AI reads or writes, and it is the unit usage is counted in.)

Are chat and coding counted together?

Yes. Usage on the Claude chat app, Claude Code and Claude Desktop counts toward the same limit, and Anthropic says usage in code editors counts too. If a colleague spends the morning asking Claude questions on the same account, that comes out of the same allowance your coding agent needs in the afternoon.

This surprises many teams. If one login is shared by several people, or one person uses the chat heavily, the coding agent can hit the wall earlier than expected.

What happens when you hit the limit?

Anthropic says you get warning messages as you approach a limit. If you reach the five-hour limit in the middle of a response, Claude Code may be allowed to finish its current step, and you would see the message "Usage limit reached · wrapping up." That extra allowance is small and capped, it counts toward your weekly limit, and it covers only a response already in progress, not a new message you send afterwards.

Anthropic says it is rolling out gradually, so it may not be on your account yet. On Pro it applies up to once per weekly period. On Max it can apply each time you reach a five-hour limit, within the weekly limit.

After that, the agent stops. The files it already changed stay changed, so you are waiting, not losing work. It is still wise to ask the agent to leave short notes on where it stopped, so the next session can pick up cleanly.

What uses up the allowance fastest?

Anthropic points to these factors:

• Length and complexity of the conversation. A long, wandering session costs more than a short, focused one. Very long conversations also trigger automatic context management, which uses more of your limit.
• The model you pick. Model choice affects how quickly usage is consumed.
• The effort level. Higher effort uses more tokens, so asking the agent to think hard on every small task adds up.
• Tools and connectors. Anthropic describes these as token-intensive.

A plain example: asking the agent to rename a button label is a cheap job. Asking it to redesign checkout, read the whole codebase, run tests and fix what fails is an expensive one. Ten of the second kind in a day will empty a meter sooner than ten of the first. This is our own illustration, not an Anthropic figure.

How can I make the allowance last longer?

Anthropic's own tips are simple, and you can ask your team to follow them:

1. Start a new conversation when a long one nears your limit.
2. Use a lower effort level for routine work.
3. Turn off extended thinking when you do not need it.
4. Turn off connected apps and tools you are not using.
5. Remove unused project files and keep the project's instructions short.

For a non-technical manager, the most useful habit is the first one: give the agent one clear job at a time. A clear brief should also help, because the agent has less to guess at, though that is common sense rather than something Anthropic measures.

Why do several AI engineers hit the limit sooner?

If you run a team of AI engineers, each one is its own working session, and all of them draw from the same plan. More engineers working in parallel will use the allowance faster than one working alone. That is the trade: you finish sooner on the clock, but you also reach the meters sooner.

So match the size of the plan to the amount of parallel work. Anthropic suggests that a Pro user who regularly hits limits consider Max 5x, and that someone on Max 5x who regularly hits them consider Max 20x. The help pages give no price or capacity figures for the tiers, so check the current pricing page before you decide.

What are my options when I hit the wall?

Anthropic lists these choices:

• Wait for the reset. Free, and fine if the work is not urgent.
• Upgrade your plan. The new limits apply right away.
• Turn on usage credits. Work carries on instead of stopping, but this is extra spending beyond your plan. Pro, Max and Team plans can buy them.
• Use a developer (Console) account with API credits. Billed at standard API rates, which are separate from plan pricing.

Two cautions. First, extra usage is real money, so decide in advance who may switch it on and what the ceiling is. Second, if the ANTHROPIC_API_KEY setting exists on the machine, Claude Code uses that key instead of your subscription, and you are charged per use. If you meant to stay on the plan, ask someone technical to check this. Anthropic says you can see your remaining allocation with the /status command, and that you can decline the API credit option when it is offered.

How do I plan work around the limits?

A few practical rules. They are our suggestions, not Anthropic's:

• Do the heavy work early in the week. Save small fixes and polish for when the meter is low.
• Start big jobs at the beginning of a session. Do not begin a large build when you are nearly out.
• Keep a buffer. Do not run the plan to the limit in the middle of a release. A stop on release day is the worst time.
• Watch the trend. If you reach the weekly limit early every week, either the work is too big for the plan or the sessions are too long.

What Atlas does today

Atlas is a team of AI engineers built on Claude Code. It runs on your own Claude Pro or Max plan, signed in with that plan, with no API keys and no per-token bill, so usage counts against the plan. Several engineers working at once use the plan's limits faster, and Max gives the most room. Atlas's price never includes Claude.

Atlas also has an optional daily budget that warns at 50% and 80% and pauses the team at 100%. Production go-lives, spending and deleting data are never decided for you.

Atlas does not yet let you set a stop point tied to the five-hour or weekly plan limits. That is coming to Atlas, built in, so it needs no setup. Until then, use the daily budget, watch your remaining allocation with /status, and follow the planning rules above.

Conclusion

Usage limits are not a fault; they are the shape of the plan you bought. Know the two meters, keep sessions short and focused, and decide in advance whether you will wait, upgrade or pay for extra. Then a limit becomes a scheduling detail instead of a surprise. The Atlas home page has more plain-language guides.

Sources

• Using Claude Code with your Pro or Max plan
• How do usage and length limits work?

Originally published on the Atlas blog.

• Claude Code exports usage metrics and events through OpenTelemetry once you set CLAUDE_CODE_ENABLE_TELEMETRY=1 and choose an exporter.
• A repository cannot switch telemetry on or point it somewhere: OTEL exporter variables in project settings files are ignored, so rollout belongs in managed settings.
• Prompt text, tool details and raw API bodies are off by default, and each has its own opt-in flag.
• Cost and token metrics can be split by model, subagent, skill, plugin and MCP server, which shows what drives your spend.
• The dollar figures are local estimates at list price (or your configured rates), not a bill. On Pro and Max plans usage is included in the subscription, so use the figures to compare, not to invoice.

To monitor Claude Code usage across a team, turn on its built-in OpenTelemetry export: set CLAUDE_CODE_ENABLE_TELEMETRY=1, pick an exporter, and point it at a collector. You then get token, cost, commit, pull request and tool-decision data in your own observability stack, tagged by model, subagent, skill and MCP server.

The Claude Code docs describe OpenTelemetry export as working on every setup and as the only option that streams per-user token and cost metrics into your own stack in near real time. This guide covers the minimum setup, a managed-settings rollout, the privacy switches, and the questions the data can answer.

Why export telemetry instead of reading /usage?

/usage is per machine. Its breakdown is computed from local session history, so usage from other devices or claude.ai is not included. That is fine for one developer and no help for a team that wants to compare weeks, repos or workflows.

Telemetry sends the signals to one place. The docs' comparison for organizations lists the alternatives by setup: the spend report and analytics dashboard on Teams and Enterprise, the Console dashboard and Claude Code Analytics API for API customers, and your cloud's billing console on Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry. On the cloud providers, OpenTelemetry (or an LLM gateway) is how you get per-user numbers.

One caveat up front: Claude Code computes dollar figures locally from token counts at list price. Pro and Max subscribers have usage included in the subscription, so a cost figure there is not a billing number. Even for API users the docs call it an estimate; the Console usage page is authoritative.

How do I turn on Claude Code OpenTelemetry?

Set environment variables before starting Claude Code. These are the documented basics:

export CLAUDE_CODE_ENABLE_TELEMETRY=1          # required
export OTEL_METRICS_EXPORTER=otlp              # otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp                 # otlp, console, none
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc        # grpc, http/json, http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

There is no default protocol, so set OTEL_EXPORTER_OTLP_PROTOCOL (or the per-signal protocol variable) for each OTLP exporter you enable. Metrics export every 60 seconds by default (OTEL_METRIC_EXPORT_INTERVAL, in milliseconds) and logs every 5 seconds (OTEL_LOGS_EXPORT_INTERVAL).

Test locally first

Before you involve a collector, print metrics to the terminal at a one-second interval:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

Or expose a Prometheus endpoint and scrape http://localhost:9464/metrics:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

To confirm a metrics pipeline works, look for claude_code.session.count, which is emitted at session start. For a logs-only setup, submit a prompt and look for the claude_code.user_prompt event. If nothing arrives, start Claude Code with claude --debug-file <path> and search the file for [3P telemetry] errors. Lines tagged [Anthropic telemetry] describe Anthropic's own operational telemetry and do not point to a problem with your setup.

Send metrics and logs to different backends

Per-signal variables override the generic ones:

export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

Per-signal headers merge with the generic OTEL_EXPORTER_OTLP_HEADERS. Metric temporality defaults to delta; set OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative if your backend expects that.

How do I roll it out to a whole team?

Put the variables in the managed settings file so they apply to every user:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

Four behaviours matter here, all from the docs:

• Claude Code ignores OTEL_* exporter variables in .claude/settings.json and .claude/settings.local.json. A repository cannot enable telemetry, choose a destination or capture content. It can still set an exporter selector to none to turn a signal off, unless managed settings, a --settings file or the starting environment already sets that variable.
• Setting OTEL_EXPORTER_OTLP_ENDPOINT in managed settings removes developer-set per-signal endpoints. Setting the protocol removes developer-set per-signal protocols. Setting headers or client key and certificate variables removes the developer-set per-signal versions of that variable and all developer-set endpoints.
• The exporter selectors (OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER, OTEL_TRACES_EXPORTER) are not locked by those endpoint rules. To lock them, set them in managed settings too; the docs say this needs v2.1.223 or later.
• Claude Code does not pass OTEL_* variables to subprocesses such as the Bash tool, hooks, MCP servers or language servers, so your own scripts do not inherit your collector credentials.

The first point is a useful safety property: a cloned repo cannot quietly redirect your telemetry.

What does Claude Code measure?

Metrics

Cost and token metrics also carry model, query_source (main, subagent or auxiliary), speed, effort, agent.name, skill.name, plugin.name, mcp_server.name and mcp_tool.name. That attribution is the valuable part: it lets you ask whether spend comes from the main conversation, a subagent, one skill or one MCP server.

Agent, skill, plugin and MCP names are redacted to custom or third-party unless OTEL_LOG_TOOL_DETAILS=1 is set.

Events

Events go through the logs exporter and share a claude_code. prefix. The useful ones:

• api_request: model, cost_usd, duration_ms, token counts, request_id.
• api_error: error, status_code, attempt.
• tool_result: tool_name, tool_use_id, success, duration_ms, decision_source.
• tool_decision: decision (accept or reject), source, permission_mode.
• user_prompt and assistant_response: lengths by default, content only if you opt in.

prompt.id links every event from one prompt. event.sequence is a per-process counter, so sort by event.timestamp first. With those you can reconstruct what one instruction cost and which tools it touched.

Traces (beta)

Set CLAUDE_CODE_ENABLE_TELEMETRY=1 and CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, then choose OTEL_TRACES_EXPORTER. Spans run from claude_code.interaction, the root span for each prompt, down to claude_code.llm_request and claude_code.tool, which has blocked_on_user and execution children. The blocked-on-user span shows how long work waited for a permission answer. The claude_code.hook span needs extra settings (ENABLE_BETA_TRACING_DETAILED=1 and BETA_TRACING_ENDPOINT), and interactive CLI sessions also need organization allowlisting.

What should I keep private?

Content capture is off by default. Opt in deliberately:

Treat the last one as sensitive data storage, since the bodies carry whatever the conversation contained. Content attributes are truncated at 60 KB by default (CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH). A sensible team default is metrics plus event metadata, with tool details on only if you want per-skill and per-server attribution and your policy allows commands in logs.

Standard attributes include session.id, user.account_uuid, user.id (a random anonymous ID) and user.email. If you do not want per-person data, check what your collector keeps.

How do I keep metric cardinality under control?

Every attribute multiplies series in your backend. Defaults:

Session ID is the usual culprit, since every session creates a new series. If you only chart by team or model, set OTEL_METRICS_INCLUDE_SESSION_ID=false. To add your own dimensions, use OTEL_RESOURCE_ATTRIBUTES, for example department=engineering,team.id=platform. Values cannot contain spaces, and quotes do not escape them.

What questions can the data answer?

Start with four panels:

1. Tokens by type over time. A high cacheCreation share next to low cacheRead suggests sessions keep rebuilding context, for example after long idle gaps.
2. Cost by agent.name, skill.name and mcp_server.name. This shows whether a subagent or an MCP server dominates. Turn on OTEL_LOG_TOOL_DETAILS=1 to see real names.
3. tool_decision rejects and blocked_on_user time. Many prompts waiting on a person point to permission rules that need tuning.
4. api_error by status_code. Rising errors or retries explain slow sessions better than guessing.

Use the same data to check changes. If you move a task type to a smaller model or lower effort, compare claude_code.cost.usage split by model and effort before and after, rather than trusting a feeling.

Where an organization pays contracted rates, the docs say cost figures, including OpenTelemetry, stay at list price unless an administrator sets the modelPricing managed setting (Claude Code v2.1.242 or later). That changes what is reported, not what is charged.

Where does Atlas fit?

Atlas is a team of AI engineers built on Claude Code. Each engineer is its own Claude Code session, signed in with your own Claude Pro or Max plan, so there are no API keys and no per-token bill. Several engineers at once use the plan's limits faster, and Max gives the most room. Atlas has an optional daily budget that warns at 50% and 80% and pauses the team at 100%, and a Network screen shows what every engineer is doing live.

Atlas does not export OpenTelemetry data today. Streaming the team's activity to a collector you own is coming to Atlas, built in, so it will need no setup on your side. Until then, if you run Claude Code yourself, the setup above works as written. Atlas is an independent product. Learn more at Atlas.

Conclusion

Telemetry is a small config change that gives you one place to see tokens, estimated cost and tool behaviour across everyone. Start with the console exporter on one machine, move to a collector, then enforce the settings through managed settings so a repository cannot change them. Keep prompt and API-body capture off unless you have a clear reason, and drop session ID from metrics if your backend struggles.

Sources

• Claude Code OpenTelemetry reference (monitoring usage)
• Manage costs effectively - Claude Code docs

Originally published on the Atlas blog.