Claude Code Tip: Give Subagents Waiting on Tests or Builds a 1-Hour Cache

This optimization tip for Claude Code subagent prompt caching comes from Vox (@Voxyz_ai) on X. It covers how to selectively assign a 1-hour cache lifetime (cacheTtl: 1h) to subagents that sit idle waiting on test suites or compilation builds.

Image source: X @Voxyz_ai

By default, a subagent's prompt cache expires after 5 minutes of inactivity. When a subagent launches a test suite or waits on build output and idles past that 5-minute mark, its next execution step is forced to reprocess the entire context from scratch. This reprocessing introduces noticeable latency compared to reading from active cache and burns significantly more against token usage limits.

However, you should not blanket-switch every subagent to a 1-hour cache. According to Anthropic's official pricing documentation, 1-hour cache writes cost 2x the base input price, whereas 5-minute cache writes cost 1.25x. Subagents that execute continuously and finish within minutes gain zero benefit from extended cache retention and simply incur higher write costs.

Deciding Cache Lifetimes by Workload Pattern

Configure cache lifetimes conditionally based on each subagent's operational profile:

• Subagents that idle over 5 minutes mid-run: For subagents waiting on test suites, local compilation, or CI completions, or those planned for resumption later, add an experimental: block with indented cacheTtl: 1h at the top of the agent definition file.
• Continuous subagents finishing quickly: Keep the default 5-minute cache for subagents that execute straightforward tasks and wrap up within several minutes.
• Global override caveat (subagentPromptCacheTtl): If you already added subagentPromptCacheTtl to your settings, it overrides individual subagent configurations and alters workflow and compaction behaviors. To tune subagents individually, remove this global key first.
• Main session cache considerations: When operating on direct API keys, third-party cloud providers, or subscription tiers drawing on usage credits beyond plan allowances, the main session also defaults to 5-minute cache expiration. If you frequently step away mid-session, consider configuring promptCacheTtl: 1h in your main settings.
• Context compaction on 1M models like Opus 5.5: Models with a 1M-token context window do not compact conversation history by default until reaching roughly 967K tokens, meaning full conversation context travels with every exchange. Executing /autocompact 400k once sets automatic compaction to trigger earlier at 400K tokens.

Per-Subagent Configuration and Prerequisites

Configuring cacheTtl on a specific subagent requires Claude Code version 2.1.248 or later.

Add the following header to the target subagent file located in either global (~/.claude/agents) or project-local (.claude/agents) directories:

experimental:
  cacheTtl: 1h

If an experimental: block already exists in the file header, add cacheTtl: 1h under that existing block rather than declaring a duplicate.

Setup Instruction Prompt

You can provide the following prompt alongside the official documentation link to Opus 5.5 in Claude Code to inspect and automate these configurations:

"Read this doc, plus the subagent docs it links to, and set up my cache lifetimes by job:
1. First run claude --version. Setting cacheTtl on a single subagent needs 2.1.248 or later. If mine is older, tell me. Don't upgrade it yourself.
2. List every subagent in ~/.claude/agents and .claude/agents. For ones that might sit idle for more than 5 minutes partway through (running tests, builds, waiting on CI), or that I'll resume later, add these two lines at the top of the file:
experimental:
  cacheTtl: 1h
If there's already an experimental block, add cacheTtl under it. Don't write a second one. Leave the ones that run straight through and finish in a few minutes on the default. Give one line of reasoning for each.
3. Check ~/.claude/settings.json, .claude/settings.json and .claude/settings.local.json (including their env blocks) and my current environment variables for subagentPromptCacheTtl, CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL or FORCE_PROMPT_CACHING_5M. If any of them is set, tell me it overrides the per-subagent settings and ask whether to remove it.
4. Ask me whether I'm on a subscription, an API key or a cloud provider. Don't read any keys yourself. Unless I'm on a subscription within its plan usage, ask whether I often step away for more than 5 minutes mid-session, and if I do, set promptCacheTtl to 1h.
Show me what you'll change first, and don't write anything until I confirm."

Original source

• Vox (@Voxyz_ai) on X: https://x.com/Voxyz_ai/status/2109056129884123370