{"_id":"@computermotivators/paperclip-claude-cache","name":"@computermotivators/paperclip-claude-cache","dist-tags":{"latest":"2026.5.2-9.1"},"versions":{"2026.5.2-9.1":{"name":"@computermotivators/paperclip-claude-cache","version":"2026.5.2-9.1","description":"Paperclip adapter for Anthropic Claude API with explicit prompt caching (cache_control breakpoints)","type":"module","exports":{".":"./dist/index.js","./server":"./dist/server/index.js","./ui":"./dist/ui/index.js","./cli":"./dist/cli/index.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"dependencies":{"@anthropic-ai/sdk":"^0.53.0","picocolors":"^1.1.1"},"peerDependencies":{"@paperclipai/adapter-utils":"*"},"peerDependenciesMeta":{"@paperclipai/adapter-utils":{"optional":true}},"devDependencies":{"@types/node":"^25.9.1","typescript":"^5.7.3"},"keywords":["paperclip","paperclipai","claude","anthropic","adapter","prompt-caching","cache-control","agent"],"author":{"name":"Computer Motivators","email":"info@computermotivators.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/computermotivators/paperclip-claude-cache.git"},"publishConfig":{"access":"public"},"_id":"@computermotivators/paperclip-claude-cache@2026.5.2-9.1","bugs":{"url":"https://github.com/computermotivators/paperclip-claude-cache/issues"},"homepage":"https://github.com/computermotivators/paperclip-claude-cache#readme","_integrity":"sha512-6dZ4uYZnafUswZxgVE66lv1BgEmM3tbOBeucepvodGfOTnBR80Y4XsNCirlLQ2+Ay8C3dk+qNRMyw0WLnPV+4Q==","_resolved":"/var/home/zoeyc/Downloads/computermotivators-paperclip-claude-cache-2026.5.29.1.tgz","_from":"file:computermotivators-paperclip-claude-cache-2026.5.29.1.tgz","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-6dZ4uYZnafUswZxgVE66lv1BgEmM3tbOBeucepvodGfOTnBR80Y4XsNCirlLQ2+Ay8C3dk+qNRMyw0WLnPV+4Q==","shasum":"494e99c53277b07e8448d0fd3c2d740d65052ccc","tarball":"https://registry.npmjs.org/@computermotivators/paperclip-claude-cache/-/paperclip-claude-cache-2026.5.2-9.1.tgz","fileCount":47,"unpackedSize":71427,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIApObf7k112jBwhg0fV6Lejg7dxh7B8iZ0+4+9R+t0VvAiAhVq8sERetNrQcEw+0mhR67l6s6ENqfjncWbhJ8SPcGw=="}]},"_npmUser":{"name":"computermotivators","email":"technology@computermotivators.com"},"directories":{},"maintainers":[{"name":"computermotivators","email":"technology@computermotivators.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/paperclip-claude-cache_2026.5.2-9.1_1780083669096_0.8422497009123628"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-29T19:41:08.898Z","2026.5.2-9.1":"2026-05-29T19:41:09.270Z","modified":"2026-05-29T19:41:09.502Z"},"maintainers":[{"name":"computermotivators","email":"technology@computermotivators.com"}],"description":"Paperclip adapter for Anthropic Claude API with explicit prompt caching (cache_control breakpoints)","homepage":"https://github.com/computermotivators/paperclip-claude-cache#readme","keywords":["paperclip","paperclipai","claude","anthropic","adapter","prompt-caching","cache-control","agent"],"repository":{"type":"git","url":"git+https://github.com/computermotivators/paperclip-claude-cache.git"},"author":{"name":"Computer Motivators","email":"info@computermotivators.com"},"bugs":{"url":"https://github.com/computermotivators/paperclip-claude-cache/issues"},"license":"MIT","readme":"# @paperclipai/adapter-claude-cached\n\nPaperclip adapter that calls the **Anthropic Messages API directly** with explicit\n`cache_control: { type: \"ephemeral\" }` breakpoints on the system prompt and skills\nblocks — guaranteeing cache hits where the standard `claude_local` (Claude Code) adapter\nrelies only on implicit caching.\n\n---\n\n## Why this adapter?\n\n| | `claude_local` | `claude_cached` |\n|---|---|---|\n| Runtime | Spawns `claude` CLI | Direct Anthropic SDK call |\n| Caching | Implicit (best-effort) | **Explicit `cache_control`** |\n| Tool ecosystem | Full Claude Code tools | Text/thinking only (extend for tools) |\n| `cachedInputTokens` telemetry | Via Claude Code output parsing | ✅ Native from API response |\n| Best for | Code-editing agents | Long system-prompt agents (Opus 4.x) |\n\nOpus 4.5 list pricing (approximate):\n- Input: $15.00 / MTok\n- Cached read: $1.50 / MTok  ← **10× cheaper**\n- Cache write: $18.75 / MTok (one-time per 5-min TTL window)\n- Output: $75.00 / MTok\n\n---\n\n## Installation\n\nDrop this package into your Paperclip monorepo under `packages/adapters/claude-cached/`\nand add it to `pnpm-workspace.yaml` if not already covered by a glob.\n\n```yaml\n# pnpm-workspace.yaml\npackages:\n  - packages/adapters/*\n```\n\n---\n\n## Registration\n\n### 1. Server (`server/src/adapters/registry.ts`)\n\n```typescript\nimport { execute as claudeCachedExecute, sessionCodec as claudeCachedSessionCodec, testEnvironment as claudeCachedTest } from \"@paperclipai/adapter-claude-cached/server\";\nimport { agentConfigurationDoc as claudeCachedDoc, models as claudeCachedModels } from \"@paperclipai/adapter-claude-cached\";\n\nconst claudeCachedAdapter: ServerAdapterModule = {\n  type: \"claude_cached\",\n  execute: claudeCachedExecute,\n  testEnvironment: claudeCachedTest,\n  sessionCodec: claudeCachedSessionCodec,\n  models: claudeCachedModels,\n  supportsLocalAgentJwt: true,\n  agentConfigurationDoc: claudeCachedDoc,\n};\n\n// Add claudeCachedAdapter to the adaptersByType map alongside existing adapters.\n```\n\n### 2. UI (`ui/src/adapters/registry.ts`)\n\nFirst, create `ui/src/adapters/claude-cached/index.ts`:\n\n```typescript\nimport type { UIAdapterModule } from \"../types\";\nimport { parseClaudeCachedStdoutLine, buildClaudeCachedConfig } from \"@paperclipai/adapter-claude-cached/ui\";\nimport { ClaudeCachedConfigFields } from \"./config-fields\";\n\nexport const claudeCachedUIAdapter: UIAdapterModule = {\n  type: \"claude_cached\",\n  label: \"Claude (Cached API)\",\n  parseStdoutLine: parseClaudeCachedStdoutLine,\n  ConfigFields: ClaudeCachedConfigFields,\n  buildAdapterConfig: buildClaudeCachedConfig,\n};\n```\n\nThen create `ui/src/adapters/claude-cached/config-fields.tsx`:\n\n```tsx\n// Minimal config fields component — extend with your UI primitives as needed.\nimport React from \"react\";\nimport type { AdapterConfigFieldsProps } from \"../types\";\n\nexport function ClaudeCachedConfigFields({ values, set }: AdapterConfigFieldsProps) {\n  return (\n    <div>\n      <label>API Key\n        <input\n          type=\"password\"\n          value={String(values[\"apiKey\"] ?? \"\")}\n          onChange={e => set(\"apiKey\", e.target.value)}\n          placeholder=\"${secrets.anthropic_api_key}\"\n        />\n      </label>\n      <label>Model\n        <input\n          value={String(values[\"model\"] ?? \"claude-opus-4-5\")}\n          onChange={e => set(\"model\", e.target.value)}\n        />\n      </label>\n      <label>Max tokens\n        <input\n          type=\"number\"\n          value={String(values[\"maxTokens\"] ?? 8192)}\n          onChange={e => set(\"maxTokens\", Number(e.target.value))}\n        />\n      </label>\n      <label>Max turns per heartbeat\n        <input\n          type=\"number\"\n          value={String(values[\"maxTurns\"] ?? 10)}\n          onChange={e => set(\"maxTurns\", Number(e.target.value))}\n        />\n      </label>\n    </div>\n  );\n}\n```\n\nThen register in `ui/src/adapters/registry.ts`:\n\n```typescript\nimport { claudeCachedUIAdapter } from \"./claude-cached\";\n// Add to adaptersByType map\n```\n\n### 3. CLI (`cli/src/adapters/registry.ts`)\n\n```typescript\nimport { printClaudeCachedStreamEvent } from \"@paperclipai/adapter-claude-cached/cli\";\n\nconst claudeCachedCLIAdapter: CLIAdapterModule = {\n  type: \"claude_cached\",\n  formatStdoutEvent: printClaudeCachedStreamEvent,\n};\n// Add to adaptersByType map\n```\n\n---\n\n## Agent config example\n\n```json\n{\n  \"name\": \"Research Analyst\",\n  \"role\": \"analyst\",\n  \"adapterType\": \"claude_cached\",\n  \"adapterConfig\": {\n    \"apiKey\": \"${secrets.anthropic_api_key}\",\n    \"model\": \"claude-opus-4-5\",\n    \"maxTokens\": 8192,\n    \"maxTurns\": 15,\n    \"thinkingBudget\": 0,\n    \"timeoutSec\": 0,\n    \"graceSec\": 15,\n    \"systemPrompt\": \"You are {{agent.name}}, a research analyst at {{company.name}}. Your task: {{context.taskId}}. Wake reason: {{context.wakeReason}}.\"\n  }\n}\n```\n\n---\n\n## How caching works in this adapter\n\n```\nSystem message blocks sent to API\n┌──────────────────────────────────────────────┐\n│ Block 1: systemPrompt text                   │\n│   cache_control: { type: \"ephemeral\" }  ◄── CACHED (TTL 5min)\n├──────────────────────────────────────────────┤\n│ Block 2: Skills content (if skillsDir set)   │\n│   cache_control: { type: \"ephemeral\" }  ◄── CACHED (TTL 5min)\n├──────────────────────────────────────────────┤\n│ Conversation history (user/assistant turns)  │\n│   (no cache_control — changes every turn)    │\n└──────────────────────────────────────────────┘\n```\n\nOn the **first** call in a 5-minute window: Anthropic writes the cache.\nOn **subsequent** calls within 5 minutes: cache_read tokens are billed at $1.50/MTok\ninstead of $15.00/MTok — a 10× reduction on the stable prefix.\n\nThe `usage.cachedInputTokens` field in `AdapterExecutionResult` is populated from\n`cache_read_input_tokens` in the API response and fed to Paperclip's budget tracking.\n\n---\n\n## Limitations\n\n- No built-in tool dispatch (bash, file I/O, etc.). This is intentional — extend\n  `execute.ts` with a tool-call loop if you need tools.\n- Cache TTL is 5 minutes (Anthropic's limit). Agents that sleep longer than 5 minutes\n  between heartbeats will miss the cache window.\n- Conversation history is trimmed to the last 40 role-turns to avoid unbounded growth.\n  Adjust the slice constant in `execute.ts` if needed.\n","readmeFilename":"README.md","_rev":"1-5f1aef968fbab1890444accad531ec15"}