cachelode

cachelode is a TypeScript library and CLI for exploring Chrome cache-entry files. It can list cache objects, inspect embedded payloads and HTTP metadata, and recover cached bodies into usable files such as PNG and JPEG.

• Reusable library API with typed errors and option objects
• Standard CLI powered by Commander
• Signature matching powered by src/sigs/signatures.json
• Cache-entry inspection with URL and response-header recovery
• Heuristic carving plus structured extraction helpers
• Fixture-backed tests for library and CLI behavior under test/fixtures/

Project Layout

• src/cli.ts - CLI entrypoint
• src/cache/list.ts - cache directory traversal and preview generation
• src/cache/inspect.ts - cache-entry inspection and metadata recovery
• src/extract/ - carving, trimming, and structured extraction helpers
• src/tui/ - React/Ink terminal UI for interactive cache browsing
• src/sigs/index.ts - signature loading and file type detection
• src/sigs/signatures.json - known file signatures
• test/ - sample cache blobs for experimentation

Installation

pnpm add cachelode

Development

Requirements: Node.js 20+ and pnpm.

pnpm install
pnpm check
pnpm build
pnpm test
pnpm start list --cache-dir ./test/fixtures

During development you can run the CLI without building:

pnpm dev list --cache-dir ./test/fixtures

To run with application debug logging enabled:

pnpm dev:debug -- tui
pnpm logs:tail

To run a single test file:

pnpm exec vitest run test/list.test.ts

Usage

cachelode list --cache-dir ~/.cache/google-chrome/Default/Cache/Cache_Data

cachelode list --cache-dir ./test/fixtures --json

cachelode inspect --in ./test/fixtures/kingfancache
cachelode carve --in ./test/fixtures/jpeg-cachefile --out-dir ./recovered --trim
cachelode extract --in ./test/fixtures/kingfancache --out-dir ./recovered
cachelode assemble --cache-dir ~/.cache/google-chrome/Default/Cache/Cache_Data --out-dir ./recovered-segments
cachelode tui

• list walks a directory and reports preview bytes, the first embedded payload match, and any recovered URL hint.
• inspect reports embedded signature offsets plus parsed response headers, cache-key text, and assembly-related metadata when they are present inside the cache entry.
• carve performs signature-based extraction and can trim PNG/JPEG/GIF/PDF outputs with format-aware end detection.
• extract uses parsed cache-entry hints and response headers for cleaner naming and payload boundaries.
• assemble scans a cache directory, groups segmented cache entries by parsed assembly keys, and recovers each provable segmented asset into a single output while surfacing assembly candidates and rejected groups.
• tui opens a React/Ink terminal UI for browsing, filtering, inspecting, and extracting cache entries interactively.

TUI keybindings

cachelode tui starts with an editable cache-directory prompt prefilled with the default Chrome cache path.

• Arrow keys or j/k move the selected cache entry.
• Tab switches focus between the always-visible filter input and the entry list.
• e prompts for an output directory, prefilled with ./recovered, and extracts the selected entry.
• r reloads the current cache directory.
• q quits while the entry list is focused.

Library API

import {
  assembleSegmentedAssets,
  CachelodeError,
  carveCacheEntry,
  determineFileType,
  extractCacheEntry,
  inspectCacheEntry,
  listCachedFiles,
} from "cachelode";

const cachedFiles = await listCachedFiles({
  cacheDir: "~/.cache/google-chrome/Default/Cache/Cache_Data",
  previewBytes: 24,
});

const inspection = await inspectCacheEntry("./test/fixtures/kingfancache");
const carved = await carveCacheEntry({
  inputPath: "./test/fixtures/jpeg-cachefile",
  outDir: "./recovered",
  trim: true,
});
const extracted = await extractCacheEntry({
  inputPath: "./test/fixtures/kingfancache",
  outDir: "./recovered",
});
const segmented = await assembleSegmentedAssets({
  cacheDir: "~/.cache/google-chrome/Default/Cache/Cache_Data",
  outDir: "./recovered-segments",
});

listCachedFiles() returns structured metadata for each file in a cache directory, inspectCacheEntry() exposes payload offsets plus cached headers and assembly metadata, carveCacheEntry() / extractCacheEntry() recover single-entry outputs, and assembleSegmentedAssets() groups related entries by parsed assembly keys to recover segmented assets from a cache directory.

When the cache directory is invalid, library calls throw CachelodeError with a stable code field such as CACHE_DIR_NOT_FOUND.

Logging

cachelode now uses a Pino-backed application logger that never writes to stdout, so JSON/text command output and the Ink TUI stay clean.

• CACHELODE_LOG_LEVEL=debug|info|warn|error|silent controls verbosity. Default: silent.
• CACHELODE_LOG_FORMAT=pretty|json controls line format. Default: pretty.
• CACHELODE_LOG_FILE=/path/to/log writes logs to a file instead of stderr.

For day-to-day debugging, pnpm dev:debug -- <command> enables debug logging and writes to .cachelode/logs/debug.log, while pnpm logs:tail follows that file.