Skip to content
Claude Code Settings Guide: Loop Usage, Model Picker, and Cache TTL
TutorialsAugust 25, 202611 min read

Claude Code Settings Guide: Loop Usage, Model Picker, and Cache TTL

Claude Code v2.1.243 added loop usage tracking, model picker settings, and prompt cache TTL controls. Here is the practical setup guide to reduce API costs.

Claude Code v2.1.243 (released August 24, 2026) shipped four settings most users have not configured yet: a Loops breakdown in /usage showing per-loop token consumption, a modelPicker setting for building a custom model list that supports Vertex and Bedrock IDs, promptCacheTtl controls to restore the 1-hour cache window Anthropic cut to 5 minutes in early 2026, and a modelPricing managed setting for enterprise teams with negotiated rates.

I keep a running list of Claude Code settings worth actually configuring. Most settings I leave at defaults. These four from v2.1.243 are not ones I would keep at defaults -- the cache TTL controls in particular address a real cost problem that has been quietly inflating API bills for production agentic workloads since Anthropic's early 2026 TTL change.

What shipped in Claude Code v2.1.243?

Claude Code v2.1.243 (released August 24, 2026) added four new configurable settings alongside six bug fixes. The features target two distinct pain points: cost visibility for teams running /loop agents, and cost optimization for API-billed users who lost the 1-hour prompt cache window when Anthropic reduced the default TTL from 60 minutes to 5 minutes in early 2026.

The four new settings are:

  • Loops breakdown in /usage -- per-loop run count, total tokens, tokens per run, and last run timestamp. Requires no configuration, just an update to v2.1.243.
  • modelPicker setting -- define a custom ordered model list with labels, including Vertex and Bedrock IDs. Configured in settings.json.
  • promptCacheTtl and subagentPromptCacheTtl -- control cache TTL per context type for API-key and cloud-provider users. Configured in settings.json.
  • modelPricing managed setting -- org-level contracted rates for accurate /cost display. Configured in the Claude Code Console.

If you run agentic Claude Code workflows with any regularity, at least two of these -- the loop breakdown and the cache TTL controls -- will directly affect how you work and what you spend. The other two are useful depending on your setup. Today's v2.1.245 patch also shipped a Linux glibc 2.44 crash fix, so update to that if you're on a recent Linux distro that crashed on startup.

Community

Stop building alone.

Join the Skool community. Ask questions, share what you're building, and learn from other people actually shipping AI agents.

Join Skool →

What does the /usage Loops breakdown show?

The Loops section in /usage displays per-loop run count, total tokens consumed, tokens per run, and the timestamp of the last run. It appears automatically once you update to v2.1.243 and run any /loop task -- no configuration needed. The breakdown appears under a "Loops" heading inside the existing /usage output, alongside your session totals.

Before this change, the only way to see how much a specific loop task consumed was to note the session total before and after -- which broke completely for multi-loop sessions. The problem compounds fast: in agentic Claude Code workflows, agents use approximately 4x more tokens than standard chat interactions. Multi-agent systems use about 15x more tokens than chat. Claude Code enterprise deployments average $13 per developer per active day, and a runaway loop that retries repeatedly on a failing test can burn significantly more than that without shipping a single working line.

Here is the scenario this solves. You set up a /loop task to run a build-test cycle on a codebase. It hits a dependency conflict and retries. It retries again. And again. You come back after a break to find the loop ran 12 times. The session total shows a large number, but you cannot tell if it was the loop or your earlier research session that drove the cost.

With the Loops breakdown, you see something like: 12 runs, 38,000 tokens per run, 456,000 total tokens, last run at 14:47. At Sonnet 4.6 input pricing ($2.00 per million tokens), that is about $0.91 in input cost for that loop session. For teams tracking cost per task or running Claude Code in automation pipelines, this is the observability baseline that has been missing from Claude Code since /loop shipped.

The practical response to seeing loop breakdowns for the first time is usually to add iteration caps or token budgets. Calibrating those limits becomes straightforward when you know what a normal loop session looks like versus a runaway one -- and you have the per-run token figure to work from.

How do you configure the model picker in Claude Code?

The modelPicker setting in settings.json lets you define an ordered list of models that appear in /model, with optional labels for each. You can use any Claude model ID -- including Vertex AI and Amazon Bedrock IDs -- and choose whether the list replaces or appends to the built-in lineup. After saving settings.json, the next /model invocation shows your custom list.

Here is a working configuration for a typical development workflow:

{
  "modelPicker": [
    { "id": "claude-sonnet-4-6", "label": "Sonnet 4.6 -- fast tasks" },
    { "id": "claude-opus-4-8", "label": "Opus 4.8 -- planning and architecture" },
    { "id": "claude-haiku-4-5-20251001", "label": "Haiku 4.5 -- cheap sweeps and formatting" }
  ]
}

For enterprise teams on Vertex AI or Bedrock, the modelPicker surfaces provider-specific IDs without requiring users to remember them. If your organization has a committed usage agreement with Google Cloud and wants sessions to default to Vertex-hosted Sonnet, add the Vertex model ID to the list with a clear label. Everyone on the team sees the same options in /model without looking up IDs.

This setting builds on two earlier model controls. The ANTHROPIC_DEFAULT_MODEL environment variable (added in v2.1.236) sets which model new sessions start on. A /model pick overrides it and persists across restarts. The modelPicker is the curation layer -- it controls what is visible in the picker so you are not scrolling through every available model to find the three you actually use.

v2.1.243 also fixed the /model picker rendering taller than the terminal window and clipping models at the bottom. It now shows only the models that fit, with the rest reachable by scrolling. If you had a long model list and noticed options disappearing, this is the fix.

Want the templates from this tutorial?

I share every workflow, prompt, and template inside the free AI Creator Hub on Skool. 500+ builders sharing what actually works.

Join Free on Skool

How do the promptCacheTtl settings work?

The promptCacheTtl and subagentPromptCacheTtl settings let API-key and cloud-provider users set cache TTL per context type. Set promptCacheTtl to 3600 to restore the 1-hour cache window for your main session. Set subagentPromptCacheTtl to 300 to keep subagents on 5 minutes. These settings do not apply to Claude.ai subscribers -- Anthropic manages TTL server-side for Max, Pro, and Teams plans.

The background: in early 2026, Anthropic reduced the default prompt cache TTL from 60 minutes to 5 minutes. For production workloads, this single change increased effective API costs by 30-60%, because cached prefixes expire before they can be reused across session lengths that regularly exceed 5 minutes. An April 2026 Claude Code update introduced ENABLE_PROMPT_CACHING_1H as a temporary workaround. The promptCacheTtl settings in v2.1.243 replace that workaround with proper per-context control.

The cost difference is real. Prompt caching reduces repeated-call input costs by approximately 90% -- from around $2.00 per million tokens for full input down to roughly $0.20 per million for cache reads on Sonnet 4.6. If you run a 100,000-token system prompt across 200 API sessions per day, the math looks like this:

  • Without caching (or with expired cache): 200 sessions x 0.1 MTok x $2.00 = $40/day
  • With 1-hour cache and sessions within the window: approximately $4/day (plus initial cache-write cost at $2.50/MTok)

The distinction between promptCacheTtl and subagentPromptCacheTtl matters architecturally. Your main session accumulates a long conversation history -- system prompt, tools, full message thread -- that grows over time and benefits from a 1-hour window. Individual subagents spawn for a bounded task: read some files, run a tool, return a result. A 5-minute TTL fits them because a subagent's context is rarely reused by another subagent within the same session.

Configuration:

{
  "promptCacheTtl": 3600,
  "subagentPromptCacheTtl": 300
}

Important caveat: prompt caches are model-scoped. If you switch models mid-session using /model, the new model has no cached copy of your accumulated context. The entire session history re-processes at full input price plus a cache-write premium for the new model. For long sessions with substantial context, avoid mid-session model switches unless necessary.

What is the modelPricing managed setting?

The modelPricing managed setting lets organizations input contracted per-model rates and a discount multiplier so /cost, the status line, and telemetry all reflect actual negotiated prices instead of Anthropic's public list prices. This is a Console-level setting configured at the org level by an admin and applies to everyone in the organization -- there is no settings.json key for it.

Enterprise teams with negotiated discounts -- common above certain spend thresholds or through AWS Marketplace and Google Cloud commitments -- were previously getting /cost output that consistently overstated their actual spend. If your contracted rate is 20% below list, every session's reported cost in /cost and on the status line was wrong by that margin. The modelPricing setting corrects this by applying your contracted rate and discount multiplier to all cost calculations inside Claude Code, making telemetry and internal budget tracking accurate.

If you are a solo developer or small team on standard API pricing, this setting does not apply -- you are already paying list rates and the default cost display is accurate. It becomes relevant once you have a direct contract with Anthropic or an enterprise commitment with a cloud provider.

The complete configuration

To enable all four v2.1.243 features with one settings.json edit, add the modelPicker array and set the two promptCacheTtl values as shown below. The Loops breakdown requires no configuration -- it appears automatically in /usage after running any /loop task in v2.1.243 or later.

{
  "modelPicker": [
    { "id": "claude-sonnet-4-6", "label": "Sonnet 4.6 -- fast tasks" },
    { "id": "claude-opus-4-8", "label": "Opus 4.8 -- planning" },
    { "id": "claude-haiku-4-5-20251001", "label": "Haiku 4.5 -- sweeps and formatting" }
  ],
  "promptCacheTtl": 3600,
  "subagentPromptCacheTtl": 300
}

After saving, run /model to verify your custom list shows up in order. Run /usage after your next /loop session to see the Loops breakdown. The cache TTL settings take effect on the next API call without visible confirmation -- you will see the difference in billing over time.

On placement: settings.json is a project-level file by default. For these settings to apply everywhere, put them in your global Claude Code settings at ~/.claude/settings.json. Project-level settings override global ones, so you can set conservative global defaults and override per-project where you are running heavy agentic work that benefits from the 1-hour cache window.

One more thing: v2.1.245 shipped today (August 25, 2026) with a Linux glibc 2.44 crash fix. If Claude Code crashes on startup after a recent glibc update on your Linux system, update to v2.1.245 before applying any of these settings.

FAQ

Where do I find the Loops breakdown in Claude Code?

Run /usage in any Claude Code session after running at least one /loop task. The Loops section appears automatically in v2.1.243 and shows per-loop run count, total tokens, tokens per run, and the last run timestamp. No configuration is needed -- update to v2.1.243 or higher and run a /loop task to populate it.

Do the promptCacheTtl settings work for Claude.ai Max subscribers?

No. The promptCacheTtl and subagentPromptCacheTtl settings only apply to direct API-key users and cloud-provider deployments on Vertex AI or Amazon Bedrock. Claude.ai subscribers on Max, Pro, or Teams plans do not control cache TTL -- Anthropic manages it server-side. If you want explicit cache TTL control, you need direct API access with an API key.

What is the difference between ANTHROPIC_DEFAULT_MODEL and the modelPicker setting?

ANTHROPIC_DEFAULT_MODEL is an environment variable that sets which model new Claude Code sessions start on. The modelPicker setting controls what models appear in the /model picker's selection list. They are complementary: the env var sets the default starting model; modelPicker curates what is available to switch to. You can set both, or either independently.

Does switching models mid-session break prompt caching?

Yes. Prompt caches are model-scoped. When you switch models via /model mid-session, the new model has no cached copy of your conversation history. Your accumulated context re-processes at full input price plus a cache-write premium for the new model. For long sessions with substantial context, avoid mid-session model switches unless the task genuinely requires a different model.

Want the templates from this tutorial?

I share every workflow, prompt, and template inside the free AI Creator Hub on Skool. 500+ builders sharing what actually works.

Join Free on Skool
AI Agents First

The daily signal from the frontier of AI agents.

Join builders, founders, and researchers getting the sharpest one-email read on what's actually shipping in AI — every morning.

No spam — unsubscribe anytime