Skip to content
Back to search

cachebro

File cache with diff tracking for AI coding agents. Drop-in MCP server that cuts token usage by 26%.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/glommer--cachebro/badge.svg)](/listings/glommer--cachebro)

HTML

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

Install

i

Install instructions from the README

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

npx cachebro init     # auto-configures Claude Code, Cursor, OpenCode

That's it. Restart your editor and cachebro is active. Agents discover it automatically.

Or configure manually — add to your MCP config (`.claude.json`, `.cursor/mcp.json`, etc.):

{
  "mcpServers": {
    "cachebro": {
      "command": "npx",
      "args": ["cachebro", "serve"]
    }
  }
}

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.

README.md · README · 155 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="logo.svg" alt="cachebro" width="200" />
  3. </p>
  4. # cachebro
  5. File cache with diff tracking for AI coding agents. Powered by [Turso](https://turso.tech), a high-performance embedded database.
  6. Agents waste most of their token budget re-reading files they've already seen. cachebro fixes this: on first read it caches the file, on subsequent reads it returns either "unchanged" (one line instead of the whole file) or a compact diff of what changed. Drop-in replacement for file reads that agents adopt on their own.
  7. ## Benchmark
  8. We ran a controlled A/B test: the same refactoring task on a 268-file TypeScript codebase ([opencode](https://github.com/sst/opencode)), same agent (Claude Opus), same prompt. The only difference: cachebro enabled vs disabled.
  9. | | Without cachebro | With cachebro |
  10. |---|---:|---:|
  11. | Total tokens | 158,248 | 117,188 |
  12. | Tool calls | 60 | 58 |
  13. | Files touched | 12 | 12 |
  14. **26% fewer tokens. Same task, same result.** cachebro saved ~33,000 tokens by serving cached reads and compact diffs instead of full file contents.
  15. The savings compound over sequential tasks on the same codebase:
  16. | Task | Tokens Used | Tokens Saved by Cache | Cumulative Savings |
  17. |------|------------:|----------------------:|-------------------:|
  18. | 1. Add session export command | 62,190 | 2,925 | 2,925 |
  19. | 2. Add --since flag to session list | 41,167 | 15,571 | 18,496 |
  20. | 3. Add session stats subcommand | 63,169 | 35,355 | 53,851 |
  21. By task 3, cachebro saved **35,355 tokens in a single task** — a 36% reduction. Over the 3-task sequence, **53,851 tokens saved out of 166,526 consumed (~24%)**.
  22. ### Agents adopt it without being told
  23. We tested whether agents would use cachebro voluntarily. We launched a coding agent with cachebro configured as an MCP server but **gave the agent no instructions about it**. The agent chose `cachebro.read_file` over the built-in Read tool on its own. The tool descriptions alone were enough.
  24. ## How it works
  25. ```
  26. First read: agent reads src/auth.ts → cachebro caches content + hash → returns full file
  27. Second read: agent reads src/auth.ts → hash unchanged → returns "[unchanged, 245 lines, 1,837 tokens saved]"
  28. After edit: agent reads src/auth.ts → hash changed → returns unified diff (only changed lines)
  29. Partial read: agent reads lines 50-60 → edit changed line 200 → returns "[unchanged in lines 50-60]"
  30. ```
  31. The cache persists in a local [Turso](https://turso.tech) (SQLite-compatible) database. Content hashing (SHA-256) detects changes. No network, no external services, no configuration beyond a file path.
  32. ## Installation
  33. ```bash
  34. npx cachebro init # auto-configures Claude Code, Cursor, OpenCode
  35. ```
  36. That's it. Restart your editor and cachebro is active. Agents discover it automatically.
  37. Or configure manually — add to your MCP config (`.claude.json`, `.cursor/mcp.json`, etc.):
  38. ```json
  39. {
  40. "mcpServers": {
  41. "cachebro": {
  42. "command": "npx",
  43. "args": ["cachebro", "serve"]
  44. }
  45. }
  46. }
  47. ```
  48. ## Usage
  49. ### As an MCP server (recommended)
  50. The MCP server exposes 4 tools:
  51. | Tool | Description |
  52. |------|-------------|
  53. | `read_file` | Read a file with caching. Returns full content on first read, "unchanged" or diff on subsequent reads. Supports `offset`/`limit` for partial reads. |
  54. | `read_files` | Batch read multiple files with caching. |
  55. | `cache_status` | Show stats: files tracked, tokens saved. |
  56. | `cache_clear` | Reset the cache. |
  57. Agents discover these tools automatically and prefer them over built-in file reads because the tool descriptions advertise token savings.
  58. ### As a CLI
  59. ```bash
  60. cachebro serve # Start the MCP server
  61. cachebro status # Show cache statistics
  62. cachebro help # Show help
  63. ```
  64. Set `CACHEBRO_DIR` to control where the cache database is stored (default: `.cachebro/` in the current directory).
  65. ### As an SDK
  66. ```typescript
  67. import { createCache } from "cachebro";
  68. const { cache, watcher } = createCache({
  69. dbPath: "./my-cache.db",
  70. sessionId: "my-session-1", // each session tracks reads independently
  71. watchPaths: ["."], // optional: watch for file changes
  72. });
  73. await cache.init();
  74. // First read — returns full content, caches it
  75. const r1 = await cache.readFile("src/auth.ts");
  76. // r1.cached === false
  77. // r1.content === "import { jwt } from ..."
  78. // Second read — file unchanged, returns confirmation
  79. const r2 = await cache.readFile("src/auth.ts");
  80. // r2.cached === true
  81. // r2.content === "[cachebro: unchanged, 245 lines, 1837 tokens saved]"
  82. // r2.linesChanged === 0
  83. // After file is modified — returns diff
  84. const r3 = await cache.readFile("src/auth.ts");
  85. // r3.cached === true
  86. // r3.diff === "--- a/src/auth.ts\n+++ b/src/auth.ts\n@@ -10,3 +10,4 @@..."
  87. // r3.linesChanged === 3
  88. // Partial read — only the lines you need
  89. const r4 = await cache.readFile("src/auth.ts", { offset: 50, limit: 10 });
  90. // Returns lines 50-59, or "[unchanged in lines 50-59]" if nothing changed there
  91. // Stats
  92. const stats = await cache.getStats();
  93. // { filesTracked: 12, tokensSaved: 53851, sessionTokensSaved: 33205 }
  94. // Cleanup
  95. watcher.close();
  96. ```
  97. ## Architecture
  98. ```
  99. packages/
  100. sdk/ cachebro — the core library
  101. - CacheStore: content-addressed file cache backed by an embedded database
  102. - FileWatcher: fs.watch wrapper for change notification
  103. - computeDiff: line-based unified diff
  104. cli/ cachebro — batteries-included CLI + MCP server
  105. ```
  106. **Database:** Single [Turso](https://turso.tech) database file with `file_versions` (content-addressed, keyed by path + hash), `session_reads` (per-session read pointers), and `stats`/`session_stats` tables. Multiple sessions and branch switches are handled correctly — each session tracks which version it last saw.
  107. **Change detection:** On every read, cachebro hashes the current file content and compares it to the cached hash. Same hash = unchanged. Different hash = compute diff, update cache. No polling, no watchers required for correctness — the hash is the source of truth.
  108. **Token estimation:** `ceil(characters * 0.75)`. Rough but directionally correct for code. Good enough for the "tokens saved" metric.
  109. ## License
  110. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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