Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

Add prompt-caching cost estimate to loop-cost (#346)

M V Abhiramc4c6fedd833c
diff --git a/patterns/registry.schema.json b/patterns/registry.schema.json
index c30ea9c..b298199 100644
--- a/patterns/registry.schema.json
+++ b/patterns/registry.schema.json
@@ -94,6 +94,7 @@
"tokens_noop": { "type": "integer", "minimum": 1000 },
"tokens_report": { "type": "integer", "minimum": 1000 },
"tokens_action": { "type": "integer", "minimum": 1000 },
+ "stable_fraction": { "type": "number", "minimum": 0, "maximum": 1 },
"suggested_daily_cap": { "type": "integer", "minimum": 10000 },
"early_exit_required": { "type": "boolean" }
}
diff --git a/patterns/registry.yaml b/patterns/registry.yaml
index edb05c3..c29c72b 100644
--- a/patterns/registry.yaml
+++ b/patterns/registry.yaml
@@ -20,6 +20,7 @@ patterns:
tokens_noop: 3000
tokens_report: 80000
tokens_action: 250000
+ stable_fraction: 0.35
suggested_daily_cap: 2000000
early_exit_required: true
@@ -41,6 +42,7 @@ patterns:
tokens_noop: 5000
tokens_report: 50000
tokens_action: 200000
+ stable_fraction: 0.35
suggested_daily_cap: 100000
early_exit_required: false
@@ -62,6 +64,7 @@ patterns:
tokens_noop: 5000
tokens_report: 50000
tokens_action: 200000
+ stable_fraction: 0.35
suggested_daily_cap: 1000000
early_exit_required: true
@@ -83,6 +86,7 @@ patterns:
tokens_noop: 5000
tokens_report: 40000
tokens_action: 150000
+ stable_fraction: 0.35
suggested_daily_cap: 200000
early_exit_required: false
@@ -104,6 +108,7 @@ patterns:
tokens_noop: 5000
tokens_report: 60000
tokens_action: 300000
+ stable_fraction: 0.35
suggested_daily_cap: 500000
early_exit_required: true
@@ -125,6 +130,7 @@ patterns:
tokens_noop: 5000
tokens_report: 35000
tokens_action: 80000
+ stable_fraction: 0.35
suggested_daily_cap: 100000
early_exit_required: false
@@ -146,5 +152,6 @@ patterns:
tokens_noop: 3000
tokens_report: 30000
tokens_action: 60000
+ stable_fraction: 0.35
suggested_daily_cap: 80000
early_exit_required: false
diff --git a/tools/loop-cost/src/cli.ts b/tools/loop-cost/src/cli.ts
index c40c164..5c3a362 100644
--- a/tools/loop-cost/src/cli.ts
+++ b/tools/loop-cost/src/cli.ts
@@ -23,6 +23,7 @@ function parseArgs(argv: string[]) {
let json = false;
let list = false;
let orchestration = 'single';
+ let withCaching = false;
for (let i = 0; i < argv.length; i++) {
const a = argv[i];
@@ -33,10 +34,11 @@ function parseArgs(argv: string[]) {
else if (a === '--conservative') conservative = true;
else if (a === '--json') json = true;
else if (a === '--list') list = true;
+ else if (a === '--with-caching') withCaching = true;
else if (a === '--help' || a === '-h') return { help: true as const };
}
- return { help: false as const, pattern, cadence, level, conservative, json, list, orchestration };
+ return { help: false as const, pattern, cadence, level, conservative, json, list, orchestration, withCaching };
}
async function loadRegistry(): Promise<RegistryDoc> {
@@ -75,6 +77,8 @@ Options:
Multi-agent action cost: single (default),
maker-checker, parallel:N, debate:R
--conservative Use slower cadence from ranges (e.g. 15m not 5m)
+ --with-caching Show estimate with prompt caching applied
+ (requires stable_fraction in the pattern's cost block)
--json Machine-readable output
--list List pattern ids
-h, --help This help
@@ -123,6 +127,7 @@ Examples:
level: args.level,
conservative: args.conservative,
orchestration: args.orchestration,
+ withCaching: args.withCaching,
});
if (args.json) console.log(JSON.stringify(result, null, 2));
diff --git a/tools/loop-cost/src/estimator.ts b/tools/loop-cost/src/estimator.ts
index 39129f3..a7fd91a 100644
--- a/tools/loop-cost/src/estimator.ts
+++ b/tools/loop-cost/src/estimator.ts
@@ -12,6 +12,10 @@ export interface PatternCost {
tokens_noop: number;
tokens_report: number;
tokens_action: number;
+ /** Fraction (0.0-1.0) of report/action tokens that are stable, repeated
+ * content (STATE.md, skills, system prompt) eligible for prompt caching.
+ * Optional — patterns without it are treated as fully variable (0). */
+ stable_fraction?: number;
suggested_daily_cap: number;
early_exit_required: boolean;
}
@@ -76,6 +80,7 @@ export interface EstimateInput {
level: ReadinessLevel;
conservative?: boolean;
orchestration?: string;
+ withCaching?: boolean;
}
export interface EstimateResult {
@@ -93,6 +98,7 @@ export interface EstimateResult {
report: { tokensPerRun: number; tokensPerDay: number };
action: { tokensPerRun: number; tokensPerDay: number };
realistic: { tokensPerRun: number; tokensPerDay: number; assumptions: string };
+ caching?: { tokensPerRun: number; tokensPerDay: number; savingsPercent: number };
};
warnings: string[];
}
@@ -168,6 +174,18 @@ function formatTokens(n: number): string {
return String(n);
}
+// Anthropic prompt caching: cache reads bill at roughly 10% of base input
+// token cost. Only the stable portion of a run's tokens (STATE.md, skills,
+// system prompt — unchanged since the last cache write) benefit; the
+// variable portion (fresh scan results, diffs) still costs full price.
+const CACHE_READ_DISCOUNT = 0.1;
+
+function applyCaching(tokensPerRun: number, stableFraction: number): number {
+ const stable = tokensPerRun * stableFraction;
+ const variable = tokensPerRun - stable;
+ return Math.round(variable + stable * CACHE_READ_DISCOUNT);
+}
+
export function estimateCost(input: EstimateInput): EstimateResult {
assertValidLevel(input.level);
const cadence = input.cadence ?? input.pattern.cadence;
@@ -190,6 +208,14 @@ export function estimateCost(input: EstimateInput): EstimateResult {
actionPerRun * mix.action;
const realisticDay = Math.round(realisticPerRun * runsPerDay);
+ let caching: EstimateResult['scenarios']['caching'];
+ if (input.withCaching && cost.stable_fraction) {
+ const cachedPerRun = applyCaching(realisticPerRun, cost.stable_fraction);
+ const cachedDay = Math.round(cachedPerRun * runsPerDay);
+ const savingsPercent = Math.round((1 - cachedPerRun / realisticPerRun) * 100);
+ caching = { tokensPerRun: cachedPerRun, tokensPerDay: cachedDay, savingsPercent };
+ }
+
const warnings: string[] = [];
if (cost.early_exit_required) {
warnings.push('Early-exit triage is required — empty watchlist should exit in <5k tokens.');
@@ -230,6 +256,7 @@ export function estimateCost(input: EstimateInput): EstimateResult {
tokensPerDay: realisticDay,
assumptions: mix.assumptions,
},
+ caching,
},
warnings,
};
@@ -252,6 +279,9 @@ export function formatEstimateHuman(r: EstimateResult): string {
lines.push(` Full triage: ${formatTokens(r.scenarios.report.tokensPerDay)} (${formatTokens(r.scenarios.report.tokensPerRun)}/run)`);
lines.push(` Action every run: ${formatTokens(r.scenarios.action.tokensPerDay)} (${formatTokens(r.scenarios.action.tokensPerRun)}/run)`);
lines.push(` Realistic blend: ${formatTokens(r.scenarios.realistic.tokensPerDay)} (${r.scenarios.realistic.assumptions})`);
+ if (r.scenarios.caching) {
+ lines.push(` With prompt caching: ${formatTokens(r.scenarios.caching.tokensPerDay)} (${r.scenarios.caching.savingsPercent}% reduction vs. realistic blend)`);
+ }
if (r.warnings.length) {
lines.push('');
lines.push('Warnings:');