Skip to content
Back to search

embers

MarketplaceWorks with Claude CodeGitHub

Claude Code plugin that keeps subagent prompt caches warm through long waits and late resumes

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 20 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Ev3nt1ne/embers with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Ev3nt1ne/embers'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ev3nt1ne--embers/badge.svg)](/listings/ev3nt1ne--embers)

HTML

<a href="/listings/ev3nt1ne--embers"><img src="/api/listings/ev3nt1ne--embers/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

From a local checkout:

claude plugin marketplace add /path/to/embers
claude plugin install embers@embers

The repository is its own one-plugin marketplace (`.claude-plugin/marketplace.json`), and a plugin from a marketplace added from a local path loads in place: edits take effect at the next session or after `/reload-plugins`. Check the manifest with `claude plugin validate .`.

Leave `subagentPromptCacheTtl` and `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` unset.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 22 lines
  1. {
  2. "name": "embers",
  3. "owner": {
  4. "name": "Ev3nt1ne",
  5. "url": "https://github.com/Ev3nt1ne"
  6. },
  7. "metadata": {
  8. "description": "Embers, a single-plugin marketplace: the plugin is this repository's root",
  9. "version": "0.1.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "embers",
  14. "source": "./",
  15. "description": "Keeps subagent prompt caches from going cold",
  16. "author": {
  17. "name": "Ev3nt1ne",
  18. "url": "https://github.com/Ev3nt1ne"
  19. }
  20. }
  21. ]
  22. }
README.md · README · 278 lines
  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="assets/embers-lockup-color-dark.svg">
  4. <img alt="Embers" src="assets/embers-lockup-color.svg" width="380">
  5. </picture>
  6. </p>
  7. # Embers
  8. A Claude Code plugin that keeps subagent prompt caches from going cold.
  9. Claude Code gives subagents a 5-minute prompt cache, even on a subscription where the main
  10. conversation gets an hour. A subagent that waits longer than that misses its cache: one blocked on
  11. a long Bash command such as a test suite, or one resumed with `SendMessage` after its manager
  12. comes back to it late. Its next request re-writes its whole context at about 25 times the price
  13. of reading it, and on a subscription that comes out of your usage limit. Embers adds three
  14. things: a general-purpose agent with a 1-hour cache for work that comes back late, a waiting rule
  15. that keeps 5-minute subagents warm while a long job runs, and a short guide in every main session
  16. on which agent to use and when to resume one or start a fresh one.
  17. ## The problem
  18. Claude Code re-sends an agent's whole context on every request, and prompt caching is what keeps
  19. that cheap: the unchanged prefix is read from the cache instead of being processed again. The
  20. cache expires after a gap with no requests. For subagents the gap is 5 minutes, even on a
  21. subscription where the main conversation gets an hour.
  22. Two patterns blow through it:
  23. - **A subagent blocked on a tool.** It runs a 15-minute test suite in one Bash call, or ends its
  24. turn to wait for a background job. The first request after the wait rewrites everything.
  25. - **Work sent back late.** The main session hands a finished subagent a follow-up 20 minutes
  26. later. The resume rewrites the agent's whole context.
  27. A measured case, from one user's two weeks of ordinary work: 117 subagents rewrote 19 cold
  28. caches of 150k to 620k tokens, about 7.1M tokens in all. Every one of them was work sent back 7
  29. to 116 minutes after the agent's last activity. At Opus 5.5 list prices that is about $35.50, of
  30. which about $34 would have been avoided had each resume found its cache warm. Public reports
  31. show the same pattern at larger scale: in one, 190 rewrites of over 100k tokens each followed
  32. test suites that ran 10 to 15 minutes and drained 54% of a weekly limit in under a day
  33. ([#103309](https://github.com/anthropics/claude-code/issues/103309)).
  34. ## How the cache works
  35. Facts from the Claude Code and API docs (checked 2026-11-19):
  36. - **Two lifetimes.** 5 minutes or 1 hour. Every request that reads the cache resets the timer,
  37. at no extra cost. The lifetime counts from the *start* of the request, so a slow turn eats
  38. into it.
  39. - **Prices, as multiples of the model's base input price.** A write to a 5-minute cache costs
  40. 1.25, a write to a 1-hour cache 2, a read 0.05 on Opus 5.5 and Sonnet 5.5 (0.1 on most other
  41. models). Output costs 5.
  42. - **Who gets which lifetime.** On a subscription within its plan usage, the main conversation
  43. gets 1 hour and everything else, subagents included, gets 5 minutes. With an API key, a cloud
  44. provider, or a subscription drawing on usage credits, everything gets 5 minutes.
  45. - **How to change it**, first match wins:
  46. 1. `FORCE_PROMPT_CACHING_5M=1`
  47. 2. the environment variable `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`
  48. 3. the setting `subagentPromptCacheTtl`
  49. 4. the agent file's `experimental: { cacheTtl: 1h }`, read from user, project and plugin agent
  50. files only
  51. 5. `ENABLE_PROMPT_CACHING_1H=1`
  52. 6. the default: 5 minutes for subagents
  53. - **A resumed subagent** can read the cache its earlier run warmed, if the cache is still alive.
  54. ## What Embers does
  55. ### The relay agent: `embers:relay`
  56. A general-purpose agent with `experimental: { cacheTtl: 1h }`. It has no `tools` field, so it
  57. inherits every tool, and no `model` field, so it runs on the model of the session that starts it.
  58. Its body is short: its expertise comes from each call's brief, and it ends with a report that
  59. keeps fact and inference apart.
  60. Its description tells the main session when to pick it: work that may come back to the same
  61. agent after the 5-minute cache would lapse, such as review rounds, ping-pong between the main
  62. session and the agent, or follow-ups deferred to later. Not one-shot tasks, where the 5-minute
  63. agent is cheaper.
  64. ### The waiting rule, for 5-minute subagents only
  65. A `SubagentStart` hook injects a short rule into every subagent whose effective cache lifetime
  66. is 5 minutes: start a command that may take longer than 170 seconds in the background, then wait
  67. for it in Bash calls of at most 170 seconds, with the Bash tool's timeout set to 200000 ms:
  68. ```
  69. timeout 170 bash -c 'until <done-condition>; do sleep 15; done'; echo rc=$?
  70. ```
  71. After each call, one short progress line from the log's `tail`, then wait again, however long
  72. the job runs. Never one long blocking call, and never the turn ended to wait for a job.
  73. The rule's first line is an exit: an agent whose own instructions say its prompt cache lasts
  74. 1 hour ignores the rule. The relay's body says so ("Your prompt cache lasts 1 hour."), so a
  75. relay the hook misjudges still does not poll for nothing.
  76. The hook works out the effective lifetime with the precedence above. It reads the environment,
  77. the `subagentPromptCacheTtl` setting in the managed, project-local, project and user settings
  78. files, and the agent's own file: the managed, project and user `agents` directories, and for a
  79. plugin agent (`plugin:name`) the plugin's `agents` directory plus any files and folders its
  80. manifest's `agents` field lists, as Claude Code loads both. A 1-hour agent, the relay or any agent of
  81. your own with `cacheTtl: 1h`, gets nothing. Anything the hook cannot read counts as 5 minutes,
  82. and the rule goes in.
  83. Main conversations never get the rule: `SubagentStart` fires only for subagents (spawned,
  84. resumed, and in-process teammates), not for the main conversation of a session, background
  85. sessions included.
  86. **If you write 1-hour agents of your own** (optional): add this line to the agent's body,
  87. below the frontmatter, where the agent reads it:
  88. ```
  89. Your prompt cache lasts 1 hour.
  90. ```
  91. Should the hook
  92. ever misjudge that agent and inject the rule, the rule's exit lets the agent ignore it. Embers
  93. never reads your agent files for this line and never changes them.
  94. ### The guide for the main session
  95. A `SessionStart` hook gives every main session, background sessions included, a few lines: why
  96. (a cache expires 5 minutes after the last request, 1 hour for the relay and background sessions,
  97. and a late message costs about 25 times a warm one), then which agent to use and when to send
  98. work back to one:
  99. - a **background session** for long project work that edits files, or must outlive the current
  100. session;
  101. - a **5-minute subagent** for a one-shot task;
  102. - **`embers:relay`** for work that may come back more than 240 seconds after the agent finishes;
  103. - **sending work back**: run `date` when a subagent finishes and keep the time; resume it within
  104. 240 seconds of its finish (59 minutes for the relay); later, resume it only if its
  105. `subagent_tokens` is under 150,000, or under 350,000 when it holds work not saved anywhere
  106. else; otherwise start a fresh agent with a brief that points to the files of the earlier work.
  107. An unknown finish time counts as a cold cache, and no `subagent_tokens` figure as over 150,000.
  108. The main session can see a subagent's context size: a background subagent's completion notice
  109. carries `<subagent_tokens>`, the size of its last request (measured against the agents' own
  110. transcripts: within 1% of the last request, not a running total).
  111. Every number in both texts comes from [config/prices.toml](config/prices.toml) through
  112. [tools/thresholds.py](tools/thresholds.py), so a price or a threshold changed there flows into
  113. what the sessions read.
  114. ## Design choices, and why
  115. - **Always refresh while waiting, with no cutoff.** Below about an hour of waiting, polling every
  116. 170 seconds is also the cheaper choice: on Opus 5.5 with a 300k context, letting the cache go
  117. cold once costs as much as about 22 polls, an hour of waiting. Past that, each further hour of
  118. polling costs about 0.95 of one rewrite, about $1.37 at 300k. A 2-hour wait costs about $2.73
  119. in polls against $1.44 for one rewrite, so the rule pays about $1.30 there for being simple:
  120. one rule, no clock to keep. ([docs/math.md](docs/math.md), section 3.)
  121. - **170 seconds, not 4 minutes.** The lifetime counts from the start of the request that launched
  122. the wait, so the turn's own generation time is part of it; background subagents move a shell
  123. command to the background after 3 minutes; and the Bash tool's default timeout is 2 minutes,
  124. so the call needs an explicit one above the loop's.
  125. - **The relay does not get the waiting rule.** A 1-hour cache survives the waits the rule exists
  126. for, and polling every 170 seconds would spend turns for nothing.
  127. - **A 1-hour cache per agent, not for every subagent.** A 1-hour write costs 2 against 1.25. For
  128. one resume, a 1-hour agent pays off only when more than about 62% of its resumes come 5 to 60
  129. minutes late. Public measurements of a blanket 1 hour range from 8.6% worse to 10.5% better,
  130. depending on the workload. A dedicated agent for the work that comes back is the defensible
  131. choice. ([docs/math.md](docs/math.md), section 2.)
  132. - **Thresholds in tokens, not in a share of the context window.** What decides between a cold
  133. resume and a fresh agent is how much work a fresh agent would have to redo, and that does not
  134. depend on the window. A percentage would move whenever the window changes. 150k and 350k are
  135. 15% and 35% of today's 1M window. ([docs/math.md](docs/math.md), section 1.)
  136. - **Leave `subagentPromptCacheTtl` unset.** Setting it, even to `5m`, outranks every agent's
  137. `cacheTtl`, so the relay would quietly get 5 minutes. The same holds for
  138. `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`. Embers sets neither. If you set one where the hook
  139. can read it (the environment, or a settings file listed above), the hook follows it: every
  140. subagent gets the lifetime you chose, and the waiting rule goes to all of them or to none.
  141. One exception: with `5m`, the relay still reads "Your prompt cache lasts 1 hour" in its own
  142. body, takes the rule's exit, and waits without it.
  143. - **Hooks, not a skill.** A skill loads only when the model decides to use it; a waiting rule has
  144. to be in force all the time.
  145. - **Unknown counts as 5 minutes.** A rule injected by mistake costs a few hundred tokens; a
  146. missing one costs a full rewrite.
  147. ## Known limits
  148. - **Usage credits.** While a subscription draws on usage credits, Claude Code ignores
  149. `cacheTtl: 1h` and drops even the main conversation to 5 minutes. The hooks cannot see this,
  150. so the relay goes uncovered by the waiting rule then, and the guide's 1-hour figures do not
  151. hold.
  152. - **A wait over an hour still goes cold**, for the relay and for a main session alike.
  153. - **Resumes inside the lifetime may still miss.** Open reports show a resumed subagent rewriting
  154. its context inside a 1-hour lifetime when its history held thinking blocks
  155. ([#94728](https://github.com/anthropics/claude-code/issues/94728),
  156. [#87215](https://github.com/anthropics/claude-code/issues/87215)). Untested on the current
  157. version. To check the relay, read its transcript: `ephemeral_1h_input_tokens` should be above
  158. zero, and a resume 10 to 50 minutes later should show `cache_read_input_tokens` close to the
  159. previous context size.
  160. - **What the hook cannot see.** A `--settings` flag, `--agents` JSON that shadows an agent file,
  161. agents in `--add-dir` directories, server-managed settings (set in an organization's admin
  162. console), MDM policies (a macOS profile or the Windows registry), and, on WSL, managed
  163. settings inherited from Windows. The hook reads only the managed settings file and its
  164. drop-in folder. Where one of these applies, the hook's answer may be wrong. In particular, an
  165. organization that sets `subagentPromptCacheTtl` to `5m` through server-managed settings, MDM
  166. or Windows gives the relay 5 minutes while the hook still sees its `cacheTtl: 1h`: the relay
  167. is left without the waiting rule.
  168. - **Time.** The main session sees no clock between turns. The guide tells it to run `date` when
  169. an agent finishes and keep the time, and to count a cache as cold when it never took that
  170. time.
  171. - **Python 3.11 or later** for the price file (`tomllib`). With an older Python, the hooks fall
  172. back to built-in copies of today's numbers, which a test keeps equal to the price file.
  173. - `python3` must be on the `PATH`; the hooks are not set up for Windows without it.
  174. ## Install
  175. From a local checkout:
  176. ```
  177. claude plugin marketplace add /path/to/embers
  178. claude plugin install embers@embers
  179. ```
  180. The repository is its own one-plugin marketplace (`.claude-plugin/marketplace.json`), and a
  181. plugin from a marketplace added from a local path loads in place: edits take effect at the next
  182. session or after `/reload-plugins`. Check the manifest with `claude plugin validate .`.
  183. Leave `subagentPromptCacheTtl` and `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` unset.
  184. ## Recompute the thresholds
  185. 1. Change a number in [config/prices.toml](config/prices.toml); each entry says where it comes
  186. from, or that it is an assumption.
  187. 2. Run `python3 tools/thresholds.py` (add `--json` for JSON, `--model sonnet-5-5` for another
  188. model, `--set section.key=value` for any number).
  189. 3. Run the tests: `python3 -m unittest discover -s tests -v`.
  190. The injected texts read the same file at every session start, so nothing else needs changing.
  191. ## Sources
  192. - [Prompt caching in Claude Code](https://code.claude.com/docs/en/prompt-caching.md): lifetimes,
  193. who gets which, the precedence, resumed subagents.
  194. - [Subagents](https://code.claude.com/docs/en/sub-agents.md): `experimental.cacheTtl`, scopes,
  195. resume.
  196. - [Hooks](https://code.claude.com/docs/en/hooks.md): `SubagentStart`, `SessionStart`,
  197. `additionalContext`, the Agent tool's `totalTokens`.
  198. - [Plugin components](https://code.claude.com/docs/en/plugins/components.md) and the
  199. [manifest reference](https://code.claude.com/docs/en/plugins-reference.md).
  200. - [Settings reference](https://code.claude.com/docs/en/settings-reference.md) and
  201. [environment variables](https://code.claude.com/docs/en/env-vars.md).
  202. - [Tools reference](https://code.claude.com/docs/en/tools-reference.md): Bash timeouts and moves
  203. to the background.
  204. - [API prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) and
  205. [pricing](https://platform.claude.com/docs/en/about-claude/pricing).
  206. - [Claude Code changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md):
  207. 2.1.248 (`cacheTtl`), 2.1.318 (3-minute move to the background in background subagents).
  208. - Reports: [#99808](https://github.com/anthropics/claude-code/issues/99808),
  209. [#110403](https://github.com/anthropics/claude-code/issues/110403),
  210. [#103309](https://github.com/anthropics/claude-code/issues/103309),
  211. [#87106](https://github.com/anthropics/claude-code/issues/87106),
  212. [#74318](https://github.com/anthropics/claude-code/issues/74318),
  213. [#94728](https://github.com/anthropics/claude-code/issues/94728),
  214. [#87215](https://github.com/anthropics/claude-code/issues/87215).
  215. - [docs/math.md](docs/math.md): every number above, derived.
  216. ## Other projects
  217. - [Airone Giallo](https://github.com/Ev3nt1ne/airone-giallo): skills and checks for running a long
  218. project with Claude Code agents.
  219. - [specgraph](https://github.com/Ev3nt1ne/airone-giallo/tree/main/graph): Airone Giallo's
  220. specification graph, usable alone; it keeps a project's decisions, requirements and assumptions
  221. as a graph and computes which of them still hold.
  222. - [cache-watch](https://github.com/Ev3nt1ne/cache-watch): warns you before your own Claude Code
  223. session's prompt cache goes cold. Embers is for subagents, cache-watch for the session you sit
  224. in.
  225. - [grammar-guard](https://github.com/Ev3nt1ne/grammar-guard): grammar and spell check for the
  226. prompts you type or dictate into Claude Code.
  227. ## License
  228. MIT, see [LICENSE](LICENSE).
  229. Embers is not affiliated with the Ember.js project or Tilde Inc., nor with Anthropic.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.