Measure Claude Code Prompt Cache

August 28, 2026 - Script status line to score prompt cache.

Introduction

30 Second Summary

A terminal can give you two official-looking places to check the same behaviour. When their labels conflict, a guess leaves you wondering whether the data changed or the display did.

In this project, you will test the running Claude Code 2.1.251 client to discover which command carries its per-session prompt-cache line. You will build a compact evidence kit that compares the terminal reading with the five counters in the emitted prompt_cache object.

What You'll Build

You will watch a frozen Claude Code session produce matching terminal plus script readings beside a five-row score that settles which command carries the cache line.

By the end of this project, you'll have:

  • A live five-field status line showing request count, hit ratio, miss count, expected rebuilds, plus tokens re-cached.
  • One same-moment evidence pair containing the terminal Prompt cache (main) line beside the script reading from the same session state.
  • A five-row equality report that scores the two surfaces out of five before naming the command or commands that carried the terminal line.
  • Secret Mission: Repeat the proof after another conversation summary. Track how expected_rebuilds changes over time while preserving five-field equality between both surfaces.

Are there any prerequisites?

You need internet access plus Claude Code access through a Pro, Max, Team, Enterprise, or Console account. The free Claude.ai plan does not include Claude Code.

Before We Start

This project settles conflicting guidance by testing the running Claude Code v2.1.251 client as the evidence source. Your conclusion will compare two surfaces of the same five counters with all five fields agreeing.

Check and Prepare Claude Code

Your evidence only counts if it comes from the exact Claude Code release under test. A different client version could expose different commands or counters.

First, you will identify your terminal environment. Then, you will inspect any existing settings before preparing one authenticated session on version 2.1.251.

In this step, get ready to:
  • Identify your terminal environment.
  • Check for an existing settings file or custom status line.
  • Prepare one authenticated Claude Code session on version 2.1.251.
Check your environment and preserve current settings

Claude Code stores user settings in ~/.claude/settings.json. Checking this file now prevents a later status-line change from overwriting configuration you already use.

macOS

The .claude folder starts with a dot, so your file browser may hide it. Using the path field lets you check it directly.

  • Confirm that your current environment is macOS Terminal.
  • Use your file browser's path field to navigate to ~/.claude.
  • Check whether settings.json exists.
  • Open settings.json in a plain-text editor if it exists.
  • Search the file for statusLine without changing it.
  • Leave the existing file untouched for the preservation step later in the project.

Windows

On Windows, ~/.claude maps to %USERPROFILE%\.claude. That location holds your user-level Claude Code settings.

  • Confirm that your current environment is Windows PowerShell.
  • Press the Windows key if your current terminal uses a different shell.
  • Type PowerShell into the search field if you need to switch shells.
  • Press Enter to start PowerShell.
  • Use your file browser's path field to navigate to %USERPROFILE%\.claude.
  • Check whether settings.json exists.
  • Open settings.json in a plain-text editor if it exists.
  • Search the file for statusLine without changing it.

Linux

The .claude folder may be hidden in your file browser. Its direct path is still ~/.claude.

  • Confirm that your current environment is a Linux terminal.
  • Use your file browser's path field to navigate to ~/.claude.
  • Check whether settings.json exists.
  • Open settings.json in a plain-text editor if it exists.
  • Search the file for statusLine without changing it.
  • Leave the existing file untouched for the preservation step later in the project.
Verify or install Claude Code 2.1.251

The running binary provides the version evidence for this project. Checking it before installing anything also protects a working installation from unnecessary changes.

Before you run the check, what result do you expect from the client already on your path?

  • Check the installed Claude Code version by running this command:
claude --version

What does this check do?

The claude executable reports the installed release. This makes the binary on your path the source of truth for the test.

✔️ I see version 2.1.251

Good, the exact client required for this measurement is already available. Leave the installation unchanged.

ⓧ I see an older version

An older client cannot produce version-specific evidence for this project. Use the current official installer for your platform before continuing.

macOS

  • Update Claude Code with the current official macOS installer by running this command:
curl -fsSL https://claude.ai/install.sh | bash
What does this installer do?

This official installer downloads the current Claude Code release for macOS. The current release is version 2.1.251 for this project.

  • Repeat the version check shown above after the installer finishes.

You should now see output containing 2.1.251.

Windows

  • Update Claude Code with the current official PowerShell installer by running this command:
irm https://claude.ai/install.ps1 | iex
What does this installer do?

This official installer downloads the current native Windows release of Claude Code. The current release is version 2.1.251 for this project.

  • Repeat the version check shown above after the installer finishes.

You should now see output containing 2.1.251.

Linux

  • Update Claude Code with the current official Linux installer by running this command:
curl -fsSL https://claude.ai/install.sh | bash
What does this installer do?

This official installer downloads the current Claude Code release for Linux. The current release is version 2.1.251 for this project.

  • Repeat the version check shown above after the installer finishes.

You should now see output containing 2.1.251.

Update still reports an older version?

  • Close the current terminal after the installer completes.
  • Start a fresh terminal so it reloads the updated executable path.
  • Repeat the version check in the fresh terminal.

Help me troubleshoot the Claude Code version update. If the mismatch remains, share the non-sensitive version output in the NextWork community.

ⓧ Command not found

Claude Code is absent or unavailable on your terminal path. Install the current release for your platform.

macOS

  • Install Claude Code with the official macOS installer by running this command:
curl -fsSL https://claude.ai/install.sh | bash
What does this installer do?

This official installer downloads Claude Code for macOS. It installs the current release that the project verifies as version 2.1.251.

  • Repeat the version check shown above after the installer finishes.

You should now see output containing 2.1.251.

Windows

  • Install Claude Code with the official native Windows installer by running this command:
irm https://claude.ai/install.ps1 | iex
What does this installer do?

This official PowerShell installer downloads native Claude Code for Windows. It installs the current release that the project verifies as version 2.1.251.

  • Repeat the version check shown above after the installer finishes.

You should now see output containing 2.1.251.

Linux

  • Install Claude Code with the official Linux installer by running this command:
curl -fsSL https://claude.ai/install.sh | bash
What does this installer do?

This official installer downloads Claude Code for Linux. It installs the current release that the project verifies as version 2.1.251.

  • Repeat the version check shown above after the installer finishes.

You should now see output containing 2.1.251.

Command still unavailable?

  • Confirm that the installer completed without a network error.
  • Close the terminal after the installer finishes.
  • Start a fresh terminal before repeating the version check.

Help me troubleshoot the missing Claude Code command. If the command remains unavailable, share the non-sensitive installer output in the NextWork community.

Authenticate one trusted session

The version check proves the client is correct. An authenticated interactive session proves the client can make the requests used in later measurements.

Authentication touches your account, so keep every credential outside screenshots and project notes. Use browser sign-in or your organization's approved API-key flow.

Before you launch the client, what would prove that both installation and account access are ready?

  • Start an interactive Claude Code session by running this command:
claude

What does this command do?

The claude command opens an interactive terminal session. A new installation starts browser sign-in unless your organization uses an approved API-key flow.

  • Complete the browser sign-in if it opens.
  • Follow your organization's approved API-key flow if it replaces browser sign-in.
  • Accept workspace trust for the directory used in this project.
  • Return to the terminal after authentication completes.
  • Confirm that Claude Code shows an authenticated interactive prompt.
  • Keep this terminal session open for every later draft, compaction, and reading.

You should now see an authenticated interactive prompt in the same session you will measure. That confirms the client, account access, and trusted workspace are ready.

Sign-in or trust not completing?

  • Confirm that your account includes Claude Code access.
  • Complete any unfinished browser authentication before returning to the terminal.
  • Review the workspace trust prompt so the later status-line command can run.

Help me troubleshoot Claude Code authentication or workspace trust. If access still fails, share only the redacted error details in the NextWork community.

Your exact client is authenticated and ready to produce version-specific evidence. Next, you will test whether human-facing labels alone are enough to generate a schema-grounded status line.

Draft From Published Labels

Your trusted Claude Code 2.1.251 session is open. That gives every draft one version-specific baseline.

Human-facing labels do not guarantee the property names inside emitted JSON. This experiment preserves the AI's first label-only choices as evidence.

In this step, get ready to:
  • Preserve any existing Claude Code settings before changing the status line.
  • Generate an uncorrected label-only status line draft.
  • Produce an exact N/5 schema-grounding score from the raw payload.
Preserve the existing configuration

Your settings file may contain preferences from earlier work. An exact backup gives you a safe restore point for cleanup.

  • Return to the file-management method you used earlier to check ~/.claude/settings.json.
  • Create a copy of ~/.claude/settings.json in the same ~/.claude directory if the file existed before this project.
  • Name the copied file ~/.claude/settings.json.prompt-cache-backup.
  • Skip the backup when ~/.claude/settings.json did not exist before this project.

When a backup is required, it now preserves the exact pre-project settings. Any earlier statusLine configuration stays available for restoration.

Generate a label-only status line

The /statusline generator turns a description into a custom status line. For this experiment, Claude Code must select its five property paths before inspecting the emitted schema.

The Five Published Labels

  • Request count.
  • Hit ratio.
  • Miss count.
  • Expected rebuilds.
  • Tokens re-cached.

Before you generate the draft, how many of its five property paths do you think will exist in the real object?

Claude Code may ask for permission to edit the script file or settings file. Approving those edits lets the generator complete this controlled draft.

macOS

  • Return to the Claude Code session from the previous step.
  • Enter /statusline in the interactive prompt.
  • Tell the generator to create ~/.claude/prompt-cache-statusline.sh.
  • Require the draft to save all stdin JSON to ~/.claude/prompt-cache-payload.json before extracting any value.
  • Require the draft to print all five published labels.
  • Require the draft to choose its property paths from those labels without inspecting a schema.
  • Require a command-type statusLine configuration that invokes the draft.
  • Approve the proposed file edits if prompted.

Windows

  • Return to the Claude Code session from the previous step.
  • Enter /statusline in the interactive prompt.
  • Tell the generator to create ~/.claude/prompt-cache-statusline.ps1.
  • Require the draft to save all stdin JSON to ~/.claude/prompt-cache-payload.json before extracting any value.
  • Require the draft to print all five published labels.
  • Require the draft to choose its property paths from those labels without inspecting a schema.
  • Require a command-type statusLine configuration that invokes the draft.
  • Approve the proposed file edits if prompted.

Linux

  • Return to the Claude Code session from the previous step.
  • Enter /statusline in the interactive prompt.
  • Tell the generator to create ~/.claude/prompt-cache-statusline.sh.
  • Require the draft to save all stdin JSON to ~/.claude/prompt-cache-payload.json before extracting any value.
  • Require the draft to print all five published labels.
  • Require the draft to choose its property paths from those labels without inspecting a schema.
  • Require a command-type statusLine configuration that invokes the draft.
  • Approve the proposed file edits if prompted.

Why Keep the First Draft?

A plausible label can lead to a plausible property name. Keeping every first guess unchanged turns that assumption into something you can measure.

The draft earns credit from the emitted object alone. Its confidence or formatting does not affect the score.

  • Leave the generated draft unchanged after Claude Code finishes.
  • Send one short prompt in the same session if the status line has not run after configuration.
  • Wait for the assistant response to finish.

Claude Code runs the configured status-line command again after the assistant response. The latest raw input should now be stored in ~/.claude/prompt-cache-payload.json.

Any blank counter output now belongs to the experiment. Keep the draft unchanged so the score reflects its original guesses.

Draft or Payload Missing?

  • Confirm that you approved the generator's proposed file edits.
  • Check that the current statusLine entry uses the command type.
  • Check that the configured command points to the draft for your operating system.

Ask for help without changing the guessed paths: Why did my generated Claude Code status line fail to create the raw payload file?

Score the draft against the emitted object

The raw payload is your schema ground truth. A guessed path earns a point only when its exact property exists under prompt_cache.

Before you inspect the object, do you expect every label to map cleanly to a property name?

  • Display ~/.claude/prompt-cache-payload.json with the same file viewer or terminal method you used to inspect settings earlier.
  • Find the prompt_cache object in the raw JSON.

You should see a prompt_cache object with its emitted property names. That object decides which draft paths receive credit.

Can't Find the Object?

  • Confirm that one assistant response completed after the status-line configuration was saved.
  • Check that the draft writes the raw input before attempting any extraction.
  • Confirm that you are reading the latest ~/.claude/prompt-cache-payload.json from the same home directory.

Get help without changing the draft's guesses: Why is prompt_cache missing from my saved Claude Code status-line payload?

💡 How the Score Works

Each of the five draft paths can earn one point. A path earns that point when the exact property exists under prompt_cache.

A real property may hold a zero value. An invented path is missing from the object and receives no point.

  • Display your platform's generated script beside the raw payload.
  • Keep the generated script unedited during the comparison.
  • Write a five-row scorecard using the published labels from earlier.
  • Compare each draft extractor path with the exact properties shown under prompt_cache.
  • Mark each row as present or missing.
  • Add one point for every present path.
  • Record the total here: your score in N/5 format.

You should now have five path results plus one exact total in N/5 format.

You have captured the AI's first attempt before hindsight could improve it. Your recorded result is your score in N/5 format.

✔️ Awesome, I've got everything!

Great. Keep the draft unchanged because its exact guesses are the evidence you need for the next step.

ⓧ I'd like to double check the full code

The first draft's source varies because Claude Code generated it from labels. Check these required artifacts while leaving every guessed path untouched.

  • Confirm that ~/.claude/prompt-cache-payload.json contains the raw status-line JSON with a prompt_cache object.
  • On Windows, confirm that ~/.claude/prompt-cache-statusline.ps1 contains the uncorrected label-based draft.
  • On macOS, confirm that ~/.claude/prompt-cache-statusline.sh contains the uncorrected label-based draft.
  • On Linux, confirm that ~/.claude/prompt-cache-statusline.sh contains the uncorrected label-based draft.
  • Confirm that the platform-specific draft saves the raw input to ~/.claude/prompt-cache-payload.json.
  • Confirm that the platform-specific draft attempts to print the five published counters.
  • Confirm that the current statusLine configuration uses the command type to invoke the draft.
  • Confirm that ~/.claude/settings.json.prompt-cache-backup exactly preserves the pre-project settings when an earlier settings file existed.

Your uncorrected draft is now frozen. Its schema score is frozen too. Next, you will replace guesses with paths proven by the emitted object.

Correct the Status Line Script

The label-only draft turned five readable counter names into a test of whether the generated paths matched reality. Your recorded score captured that gap before any correction.

The raw prompt_cache object from Claude Code now supplies the observed schema. This step uses those properties to produce one normalized reading from the same payload.

In this step, get ready to:
  • Replace every guessed property path with its observed equivalent.
  • Confirm that the existing configuration invokes the corrected platform script.
  • Produce a fresh five-field reading from one final response.
Replace guessed paths with verified paths

A counter becomes measurable when its property path exists in the emitted object. The captured payload gives you five exact paths for the five displayed labels.

How Do the Fields Map?

  • Request count comes from prompt_cache.requests.
  • Hit ratio comes from prompt_cache.hit_ratio.
  • Miss count comes from prompt_cache.misses.
  • Expected rebuilds come from prompt_cache.expected_rebuilds.
  • Tokens re-cached come from prompt_cache.miss_recache_tokens.

Choose the platform that contains your draft. The corrected file preserves every raw payload before formatting its five values.

macOS

  • Switch back to the file editor you used to inspect the draft.
  • Select ~/.claude/prompt-cache-statusline.sh in the editor sidebar.
  • Select all of the label-only draft.
  • Replace it with the verified Bash file in the double-check tab below.

✔️ Awesome, I've got everything!

Your Bash file now reads the five verified properties from the emitted object.

ⓧ I'd like to double check the full code

Full Bash File in Two Parts
  • Paste Part 1 into ~/.claude/prompt-cache-statusline.sh.
  • Place Part 2 directly below Part 1.
  • Save ~/.claude/prompt-cache-statusline.sh.
Part 1 of 2
#!/usr/bin/env bash

# Capture the payload from Claude Code.
input=$(cat)

# Define the output paths.
root="$HOME/.claude"
payload_path="$root/prompt-cache-payload.json"
reading_path="$root/prompt-cache-reading.txt"

# Preserve the complete payload for inspection.
mkdir -p "$root"
printf '%s\n' "$input" > "$payload_path"

# Isolate the prompt_cache object.
flat=$(printf '%s' "$input" | tr -d '\r\n')
cache=$(printf '%s' "$flat" | sed -n 's/.*"prompt_cache"[[:space:]]*:[[:space:]]*{\([^}]*\)}.*/\1/p')

# Return a readable status before the first response.
if [ -z "$cache" ]; then
  waiting="Prompt cache: waiting for first API response"
  printf '%s\n' "$waiting" | tee "$reading_path"
  exit 0
fi

# Extract one primitive field from the cache object.
field() {
  printf '%s' "$cache" \
    | sed -n "s/.*\"$1\"[[:space:]]*:[[:space:]]*\([^,}]*\).*/\1/p" \
    | tr -d ' \"'
}
Part 2 of 2
# Format large token counts for the status line.
format_tokens() {
  awk -v value="$1" 'BEGIN {
    if (value >= 1000000) {
      scaled = value / 1000000
      suffix = "m"
    } else if (value >= 1000) {
      scaled = value / 1000
      suffix = "k"
    } else {
      printf "%.0f", value
      exit
    }
    text = sprintf("%.1f", scaled)
    sub(/\.0$/, "", text)
    printf "%s%s", text, suffix
  }'
}

# Read the five verified cache fields.
requests=$(field requests)
hit_raw=$(field hit_ratio)
misses=$(field misses)
expected_rebuilds=$(field expected_rebuilds)
miss_recache_tokens=$(field miss_recache_tokens)

# Convert the hit ratio to a whole percentage.
if [ "$hit_raw" = "null" ] || [ -z "$hit_raw" ]; then
  hit_ratio="null"
else
  hit_ratio=$(awk -v ratio="$hit_raw" 'BEGIN { printf "%.0f%%", ratio * 100 }')
fi

# Build and save the normalized reading.
recached=$(format_tokens "$miss_recache_tokens")
line="requests=$requests | hit_ratio=$hit_ratio | misses=$misses | expected_rebuilds=$expected_rebuilds | tokens re-cached=$recached"

printf '%s\n' "$line" | tee "$reading_path"

💡 What Does This Script Do?

  • The opening section preserves the complete input in prompt-cache-payload.json.
  • The field() helper extracts primitive values from the captured object.
  • The format_tokens() helper converts large token counts into compact text.
  • The final section converts hit_ratio into a whole percentage.
  • The final line reaches the status display through tee. The same line is saved in prompt-cache-reading.txt.
  • Save ~/.claude/prompt-cache-statusline.sh.
  • Open a second operating-system terminal using the same method from Step 1.
  • Make the corrected Bash file executable by running:
chmod +x ~/.claude/prompt-cache-statusline.sh

What Does This Command Do?

The command grants executable permission to the Bash file. Claude Code can invoke the file as its status-line command.

A clean return to the terminal prompt confirms that the permission change completed.

Cannot Change the Script Permission?

Confirm that ~/.claude/prompt-cache-statusline.sh exists under your current home directory.

Check that your terminal account owns the file before retrying the command.

Help me check the script path and file permissions.

Windows

  • Switch back to the file editor you used to inspect the draft.
  • Select ~/.claude/prompt-cache-statusline.ps1 in the editor sidebar.
  • Select all of the label-only draft.
  • Replace it with the verified PowerShell file in the double-check tab below.

✔️ Awesome, I've got everything!

Your PowerShell file now reads the five verified properties from the emitted object.

ⓧ I'd like to double check the full code

$raw = $input | Out-String
$root = Join-Path $HOME ".claude"
$payloadPath = Join-Path $root "prompt-cache-payload.json"
$readingPath = Join-Path $root "prompt-cache-reading.txt"

New-Item -ItemType Directory -Force -Path $root | Out-Null
Set-Content -LiteralPath $payloadPath -Value $raw -Encoding utf8

$data = $raw | ConvertFrom-Json
$cache = $data.prompt_cache

if ($null -eq $cache) {
    $waiting = "Prompt cache: waiting for first API response"
    Set-Content -LiteralPath $readingPath -Value $waiting -Encoding utf8
    Write-Output $waiting
    exit 0
}

$culture = [System.Globalization.CultureInfo]::InvariantCulture

function Format-CompactTokens([double]$value) {
    if ($value -ge 1000000) {
        return [string]::Format($culture, "{0:0.#}m", ($value / 1000000))
    }
    if ($value -ge 1000) {
        return [string]::Format($culture, "{0:0.#}k", ($value / 1000))
    }
    return [string]::Format($culture, "{0:0}", $value)
}

if ($null -eq $cache.hit_ratio) {
    $hitRatio = "null"
} else {
    $hitRatio = [string]::Format($culture, "{0:0}", ([double]$cache.hit_ratio * 100)) + "%"
}

$recached = Format-CompactTokens ([double]$cache.miss_recache_tokens)
$line = "requests=$($cache.requests) | hit_ratio=$hitRatio | misses=$($cache.misses) | expected_rebuilds=$($cache.expected_rebuilds) | tokens re-cached=$recached"

Set-Content -LiteralPath $readingPath -Value $line -Encoding utf8
Write-Output $line
What Does This Script Do?
  • The opening section preserves the complete input in prompt-cache-payload.json.
  • The waiting branch handles input that does not contain a prompt_cache object.
  • The Format-CompactTokens() function converts large token counts into compact text.
  • The final section converts hit_ratio into a whole percentage.
  • The same normalized line is saved in prompt-cache-reading.txt before it reaches the status display.
  • Save ~/.claude/prompt-cache-statusline.ps1.

The saved file should now contain $cache.requests. It should also contain the other four verified property references.

Missing a PowerShell Status Value?

Compare the five property references with the matching names in ~/.claude/prompt-cache-payload.json.

Check that copied quotation marks match the verified file.

Help me find the incorrect property reference.

Linux

  • Switch back to the file editor you used to inspect the draft.
  • Select ~/.claude/prompt-cache-statusline.sh in the editor sidebar.
  • Select all of the label-only draft.
  • Replace it with the verified Bash file in the double-check tab below.

✔️ Awesome, I've got everything!

Your Bash file now reads the five verified properties from the emitted object.

ⓧ I'd like to double check the full code

Full Bash File in Two Parts
  • Paste Part 1 into ~/.claude/prompt-cache-statusline.sh.
  • Place Part 2 directly below Part 1.
  • Save ~/.claude/prompt-cache-statusline.sh.
Part 1 of 2
#!/usr/bin/env bash

# Capture the payload from Claude Code.
input=$(cat)

# Define the output paths.
root="$HOME/.claude"
payload_path="$root/prompt-cache-payload.json"
reading_path="$root/prompt-cache-reading.txt"

# Preserve the complete payload for inspection.
mkdir -p "$root"
printf '%s\n' "$input" > "$payload_path"

# Isolate the prompt_cache object.
flat=$(printf '%s' "$input" | tr -d '\r\n')
cache=$(printf '%s' "$flat" | sed -n 's/.*"prompt_cache"[[:space:]]*:[[:space:]]*{\([^}]*\)}.*/\1/p')

# Return a readable status before the first response.
if [ -z "$cache" ]; then
  waiting="Prompt cache: waiting for first API response"
  printf '%s\n' "$waiting" | tee "$reading_path"
  exit 0
fi

# Extract one primitive field from the cache object.
field() {
  printf '%s' "$cache" \
    | sed -n "s/.*\"$1\"[[:space:]]*:[[:space:]]*\([^,}]*\).*/\1/p" \
    | tr -d ' \"'
}
Part 2 of 2
# Format large token counts for the status line.
format_tokens() {
  awk -v value="$1" 'BEGIN {
    if (value >= 1000000) {
      scaled = value / 1000000
      suffix = "m"
    } else if (value >= 1000) {
      scaled = value / 1000
      suffix = "k"
    } else {
      printf "%.0f", value
      exit
    }
    text = sprintf("%.1f", scaled)
    sub(/\.0$/, "", text)
    printf "%s%s", text, suffix
  }'
}

# Read the five verified cache fields.
requests=$(field requests)
hit_raw=$(field hit_ratio)
misses=$(field misses)
expected_rebuilds=$(field expected_rebuilds)
miss_recache_tokens=$(field miss_recache_tokens)

# Convert the hit ratio to a whole percentage.
if [ "$hit_raw" = "null" ] || [ -z "$hit_raw" ]; then
  hit_ratio="null"
else
  hit_ratio=$(awk -v ratio="$hit_raw" 'BEGIN { printf "%.0f%%", ratio * 100 }')
fi

# Build and save the normalized reading.
recached=$(format_tokens "$miss_recache_tokens")
line="requests=$requests | hit_ratio=$hit_ratio | misses=$misses | expected_rebuilds=$expected_rebuilds | tokens re-cached=$recached"

printf '%s\n' "$line" | tee "$reading_path"

💡 What Does This Script Do?

  • The opening section preserves the complete input in prompt-cache-payload.json.
  • The field() helper extracts primitive values from the captured object.
  • The format_tokens() helper converts large token counts into compact text.
  • The final section converts hit_ratio into a whole percentage.
  • The final line reaches the status display through tee. The same line is saved in prompt-cache-reading.txt.
  • Save ~/.claude/prompt-cache-statusline.sh.
  • Open a second operating-system terminal using the same method from Step 1.
  • Make the corrected Bash file executable by running:
chmod +x ~/.claude/prompt-cache-statusline.sh

What Does This Command Do?

The command grants executable permission to the Bash file. Claude Code can invoke the file as its status-line command.

A clean return to the terminal prompt confirms that the permission change completed.

Cannot Change the Script Permission?

Confirm that ~/.claude/prompt-cache-statusline.sh exists under your current home directory.

Check that your terminal account owns the file before retrying the command.

Help me check the script path and file permissions.

Confirm the status-line configuration

The corrected script runs through the existing statusLine object. Its command must point to the platform file without replacing unrelated settings.

macOS

  • Switch back to ~/.claude/settings.json in your file editor.
  • Preserve every unrelated top-level setting.
  • Set statusLine.type to command.
  • Set statusLine.command to ~/.claude/prompt-cache-statusline.sh.
  • Save ~/.claude/settings.json.

Windows

  • Switch back to ~/.claude/settings.json in your file editor.
  • Preserve every unrelated top-level setting.
  • Set statusLine.type to command.
  • Set statusLine.command to powershell -NoProfile -File ~/.claude/prompt-cache-statusline.ps1.
  • Save ~/.claude/settings.json.

Linux

  • Switch back to ~/.claude/settings.json in your file editor.
  • Preserve every unrelated top-level setting.
  • Set statusLine.type to command.
  • Set statusLine.command to ~/.claude/prompt-cache-statusline.sh.
  • Save ~/.claude/settings.json.

Claude Code reloads the settings automatically after you save the file. The trusted session now invokes the corrected platform script.

Status Line Still Blank?

Confirm that the session still trusts the current workspace.

Check that the configured command points to the script for your operating system. Validate that ~/.claude/settings.json contains strict JSON.

Help me diagnose the blank status line.

Produce a fresh script reading

One final build-time response refreshes the raw payload. The same status-line run writes the normalized evidence file.

Before you send the prompt, do you expect every verified property to produce a visible value?

  • Send the final build-time prompt by entering Reply exactly READY. in the open Claude Code session.

Claude Code replies READY.. The refreshed status line shows requests, hit ratio, misses, expected rebuilds, and tokens re-cached.

  • Switch back to the file editor from earlier.
  • Open ~/.claude/prompt-cache-reading.txt.
  • Compare its normalized line with the visible status line.
  • Open ~/.claude/prompt-cache-payload.json.
  • Confirm that its prompt_cache object contains all five verified properties.

That is the correction complete. The visible status line and prompt-cache-reading.txt now contain the same normalized reading from the latest raw payload.

Reading File Does Not Match?

Confirm that prompt-cache-reading.txt was updated after the READY. response.

Check that the script writes $line on Windows. Check that it writes line on macOS or Linux.

Help me diagnose the stale reading.

Your evidence kit now has a schema-grounded reading. Next, you will prove why readings separated by a model turn cannot count as one measurement.

Control Timing and Rebuild

Your corrected Claude Code status line now displays five prompt-cache counters. It also saves the matching normalized reading.

A model turn advances the request counters. This makes an older terminal value stale.

Compaction creates a legitimate expected rebuild. This step separates that expected change from disagreement between the two surfaces.

In this step, get ready to:
  • Observe a stale request-count mismatch after one controlled model turn.
  • Compact the conversation to begin a new measurement phase.
  • Create one post-compaction reading before freezing further model turns.
Demonstrate a stale comparison

An atomic measurement compares both surfaces at one session state. A completed model response moves the session to a new state.

  • Display the current terminal prompt-cache reading in your open Claude Code session by entering:
/cost

What does this reading establish?

The /cost output gives you a terminal reading from the current session state. Its Prompt cache (main) line includes the request count you need for this demonstration.

  • Record the terminal request count here: request count before the model turn.

Before you send the next prompt, do you think the earlier terminal count can still match the script reading after another response?

  • Advance the main conversation by entering this exact prompt:
Reply exactly ADVANCED.

Why does this change the reading?

The assistant response adds another main-conversation API request. Claude Code then reruns the status-line script with the updated session data.

  • Wait until the assistant responds with ADVANCED..
  • Record the updated script request count here: request count after the model turn.
  • Compare the updated script count with the earlier terminal count.

The two request counts should now differ. The earlier /cost value is stale.

That mismatch is useful. It proves that the comparison captured two different session states.

Request count did not change?

  • Confirm that ADVANCED. came from the assistant in the same Claude Code session.
  • Wait for the status line to refresh after the response completes.
  • Check the request count in the visible normalized status line.

Help me diagnose why my request count did not change after the assistant response.

Compact the conversation

Compaction rewrites the active conversation context. The next cache rebuild belongs to a new measurement phase.

  • Summarize the open conversation by entering this exact command:
/compact Keep only the measurement protocol, the five counter names, and the first-draft score.

Why does this start a new phase?

The command preserves the measurement protocol while replacing the longer conversation with a summary. Claude Code reruns the status-line script when compaction finishes.

A post-compaction object describes the rewritten conversation state. Pre-compaction readings belong to the earlier phase.

  • Wait for compaction to finish.
  • Confirm that the status line refreshes after the summary completes.
  • Separate the pre-compaction readings from this new measurement phase.

You have now created the boundary between the stale demonstration and the final measurement phase. The next response populates the rewritten conversation once.

Create the post-compaction reading

The first assistant response after compaction rebuilds the rewritten conversation in the cache. The prompt_cache.expected_rebuilds value identifies rebuilds explained by conversation compaction.

Before you send the next prompt, do you expect this response to preserve the old measurement phase or establish a new one?

  • Create exactly one post-compaction response by entering this exact prompt:
Reply exactly REBUILT.

What does this response prove?

This is the first model request after the conversation rewrite. Claude Code records an expected rebuild when compaction explains the cache rewrite.

The status-line script saves this response's raw JSON to ~/.claude/prompt-cache-payload.json. It saves the normalized line to ~/.claude/prompt-cache-reading.txt.

  • Wait until the assistant responds with REBUILT..
  • Record the displayed expected-rebuild value here: expected rebuild count after compaction.
  • Confirm that the visible status line shows the complete normalized reading.
  • Stop sending natural-language prompts in this Claude Code session.

What should you see?

  • A requests value for the new measurement phase.
  • A normalized hit_ratio value.
  • A misses value.
  • An expected_rebuilds value that you have recorded.
  • A compact tokens_re-cached value.

The raw payload and normalized reading now belong to the first post-compaction response. Your session is frozen at the state needed for the final comparison.

Post-compaction reading did not refresh?

  • Confirm that REBUILT. appeared as the assistant response.
  • Wait for the status line to finish processing the new session data.
  • Keep using the same trusted Claude Code session from the earlier steps.

Help me diagnose why my post-compaction prompt-cache reading did not refresh.

Your measurement phase is now frozen at one known session state. Next, you can read both surfaces without advancing the counters.

Capture Same-Moment Evidence

Your stale comparison showed how one extra model turn advances the session's prompt caching counters. That timing error proved that two correct readings can disagree when they describe different moments.

This step freezes one Claude Code 2.1.251 state for both readings. You will compare the terminal output against the emitted status-line object one field at a time.

In this step, get ready to:
  • Test both candidate slash commands without advancing the model.
  • Pair every terminal prompt-cache line with the frozen script reading.
  • Produce a five-field equality report with an evidence-backed finding.
Test both candidate commands

This capture is a little fiddly because one natural-language prompt advances the counters. Slash commands let you inspect the frozen session without creating another model turn.

  • Return to the trusted Claude Code session from the previous step.
  • Keep the session frozen by entering no natural-language prompts.
  • Test the first candidate by entering this command in the open session:
/cost

What Does This Check?

The v2.1.251 release note names /cost for the per-session prompt-cache line. Your observation records what the installed client actually displays.

  • Record whether the output includes Prompt cache (main).
  • Copy the complete Prompt cache (main) line into your notes if it appears.
  • Test the second candidate by entering this command without sending a model prompt:
/usage

What Does This Check?

The current command documentation places the per-session summary under /usage. Your observed output determines which command names belong in the final finding.

  • Record whether the output includes Prompt cache (main).
  • Copy the complete Prompt cache (main) line into your notes if it appears.
  • Record every command that displayed the line here: observed command or commands.

Missing the Prompt-Cache Line?

  • Confirm that you are still using the trusted session from earlier.
  • Confirm that the main conversation completed the post-compaction response before you froze model turns.
  • Confirm that the running client reports version 2.1.251.

Ask for help with the missing output: Why is the prompt-cache line missing from my slash-command output?

Pair the terminal and script readings

The visible status line still represents the first post-compaction response. Pairing that text with each captured terminal line keeps every value tied to the same request count.

  • Read the normalized five-field status line already displayed in the open Claude Code session.
  • Copy the exact normalized text into your notes under a Script reading label.
  • Place the script reading beside every captured Prompt cache (main) line.
  • Confirm that the script's expected_rebuilds value matches the first post-compaction value you recorded.
  • Leave ~/.claude/prompt-cache-payload.json unchanged as the raw evidence for this frozen state.
  • Leave ~/.claude/prompt-cache-reading.txt unchanged as the saved script reading for this pair.

That is the delicate capture complete. Your terminal evidence now describes the same frozen session state as the script reading.

Compare all five fields

Before you compare the frozen pair, do you expect every normalized field to agree?

  • Add a heading named first-same-moment-equality-report to your notes.
  • Complete the request count row with its terminal value plus its script value plus its equality result.
  • Complete the hit ratio row with its terminal value plus its script value plus its equality result.
  • Complete the miss count row with its terminal value plus its script value plus its equality result.
  • Complete the expected rebuilds row with its terminal value plus its script value plus its equality result.
  • Complete the tokens re-cached row with its terminal value plus its script value plus its equality result.
  • Total the rows marked equal as a score out of 5.

A total of 5/5 proves that the two surfaces agree at the frozen moment. A lower total identifies a display mismatch that needs to remain visible in your evidence.

  • Preserve the evidence pair if your total is lower than 5/5.
  • Name every mismatched field in the report if your total is lower than 5/5.
  • Record your equality total here: your N/5 score.
  • Write the evidence-backed finding in this format:

Finding: In Claude Code 2.1.251, observed command or commands carried the terminal prompt-cache line. your N/5 score fields matched the status-line object.

Strong work. Your finding is backed by five explicit comparisons from one frozen session state.

Secret mission

Secret Mission: Repeat the Proof After Another Summary

Repeat the same-moment proof after a second conversation summary. You will confirm whether both surfaces still agree while tracking the legitimate change in the expected-rebuild counter across time.

Clean Up Your Resources

Clean Up Your Resources

Your custom Claude Code 2.1.251 status line runs locally without consuming API tokens. The only ongoing usage comes from new model prompts through your plan allowance or normal API billing.

Resources you used:

  • One open trusted Claude Code session.
  • One command-based statusLine configuration in ~/.claude/settings.json.
  • One corrected Windows script at ~/.claude/prompt-cache-statusline.ps1.
  • One corrected macOS or Linux script at ~/.claude/prompt-cache-statusline.sh.
  • The latest raw payload at ~/.claude/prompt-cache-payload.json.
  • The latest normalized reading at ~/.claude/prompt-cache-reading.txt.
  • The conditional settings backup at ~/.claude/settings.json.prompt-cache-backup when a settings file existed before the project.

Keep everything running

No action is needed. Choose this option if you want prompt-cache visibility available in future Claude Code sessions.

The status-line script continues to run locally when Claude Code refreshes it. The script does not consume API tokens by itself.

  • Keep the project statusLine object in ~/.claude/settings.json.
  • Keep the corrected script for your platform.
  • Keep ~/.claude/prompt-cache-payload.json as the raw evidence behind your corrected property paths.
  • Keep ~/.claude/prompt-cache-reading.txt as the normalized reading from your second frozen measurement.
  • End the open Claude Code session when you finish making model requests.

Pause - I'll come back to this later

This option ends live project activity while preserving the corrected scripts and evidence files for another measurement session.

macOS

  • End the open Claude Code session using the terminal's normal session-exit control.
  • Use Finder's folder navigation to open ~/.claude.
  • Restore ~/.claude/settings.json from ~/.claude/settings.json.prompt-cache-backup when the backup exists.
  • Remove only the project statusLine object from ~/.claude/settings.json when no backup exists.
  • Save ~/.claude/settings.json.
  • Confirm that the settings match the backup when one existed.
  • Confirm that the project statusLine object is absent when no backup existed.
  • Confirm that the corrected script and evidence files remain in ~/.claude.

Windows

  • End the open Claude Code session using the terminal's normal session-exit control.
  • Use File Explorer to open the ~/.claude folder from earlier.
  • Restore ~/.claude/settings.json from ~/.claude/settings.json.prompt-cache-backup when the backup exists.
  • Remove only the project statusLine object from ~/.claude/settings.json when no backup exists.
  • Save ~/.claude/settings.json.
  • Confirm that the settings match the backup when one existed.
  • Confirm that the project statusLine object is absent when no backup existed.
  • Confirm that the corrected script and evidence files remain in ~/.claude.

Linux

  • End the open Claude Code session using the terminal's normal session-exit control.
  • Use your file manager to open ~/.claude.
  • Restore ~/.claude/settings.json from ~/.claude/settings.json.prompt-cache-backup when the backup exists.
  • Remove only the project statusLine object from ~/.claude/settings.json when no backup exists.
  • Save ~/.claude/settings.json.
  • Confirm that the settings match the backup when one existed.
  • Confirm that the project statusLine object is absent when no backup existed.
  • Confirm that the corrected script and evidence files remain in ~/.claude.

Delete - I don't want to use this again

Removing these files is final for this evidence kit. Your Claude Code installation and account remain untouched.

macOS

  • End the open Claude Code session using the terminal's normal session-exit control.
  • Use Finder's folder navigation to open ~/.claude.
  • Restore ~/.claude/settings.json from ~/.claude/settings.json.prompt-cache-backup when the backup exists.
  • Remove only the project statusLine object from ~/.claude/settings.json when no backup exists.
  • Save ~/.claude/settings.json.
  • Delete ~/.claude/prompt-cache-statusline.ps1, ~/.claude/prompt-cache-statusline.sh, ~/.claude/prompt-cache-payload.json, ~/.claude/prompt-cache-reading.txt, and ~/.claude/settings.json.prompt-cache-backup when those files exist.
  • Confirm that the settings match the backup when one existed.
  • Confirm that the project statusLine object is absent when no backup existed.
  • Confirm that the project scripts and evidence files are absent from ~/.claude.

Windows

  • End the open Claude Code session using the terminal's normal session-exit control.
  • Use File Explorer to open the ~/.claude folder from earlier.
  • Restore ~/.claude/settings.json from ~/.claude/settings.json.prompt-cache-backup when the backup exists.
  • Remove only the project statusLine object from ~/.claude/settings.json when no backup exists.
  • Save ~/.claude/settings.json.
  • Delete ~/.claude/prompt-cache-statusline.ps1, ~/.claude/prompt-cache-statusline.sh, ~/.claude/prompt-cache-payload.json, ~/.claude/prompt-cache-reading.txt, and ~/.claude/settings.json.prompt-cache-backup when those files exist.
  • Confirm that the settings match the backup when one existed.
  • Confirm that the project statusLine object is absent when no backup existed.
  • Confirm that the project scripts and evidence files are absent from ~/.claude.

Linux

  • End the open Claude Code session using the terminal's normal session-exit control.
  • Use your file manager to open ~/.claude.
  • Restore ~/.claude/settings.json from ~/.claude/settings.json.prompt-cache-backup when the backup exists.
  • Remove only the project statusLine object from ~/.claude/settings.json when no backup exists.
  • Save ~/.claude/settings.json.
  • Delete ~/.claude/prompt-cache-statusline.ps1, ~/.claude/prompt-cache-statusline.sh, ~/.claude/prompt-cache-payload.json, ~/.claude/prompt-cache-reading.txt, and ~/.claude/settings.json.prompt-cache-backup when those files exist.
  • Confirm that the settings match the backup when one existed.
  • Confirm that the project statusLine object is absent when no backup existed.
  • Confirm that the project scripts and evidence files are absent from ~/.claude.

Nice Work!

🎉 Mission Accomplished

Excellent work. You turned conflicting command guidance into a measured result for Claude Code 2.1.251.

Your two frozen-session reports now show whether the terminal and status line agree across all five counters used to measure prompt caching.

You've learned how to:

  • Build a five-counter status line from Claude Code's emitted prompt_cache object. Preserve the raw payload as evidence. Save a normalized reading for direct comparison.
  • Measure the AI draft against the emitted schema. Correct every guessed path with fields observed in the raw object.
  • Freeze model turns during an atomic capture. Compare /cost, /usage, and the script reading field by field. Publish an evidence-backed finding that names the observed command or commands.
  • Secret Mission: Repeat the same-moment proof after a second conversation summary. Track the new expected_rebuilds value separately from cross-surface equality.

Ready to quiz yourself?