Skip to content
beachcomb
From the team behind Coconut

Turn the pile into answers you can stand behind.

Beachcomb reads every document once, saves the careful reading for the ones that matter, notes where each fact came from, and next time reads only what’s new.

For your engineer: one YAML file. Cheap models inventory everything, expensive models read what matters, every claim is cited, re-runs cost only what changed.

Fig. 01 — Shaken out. Everything comes in, the noise falls away, and what is left is filed by theme.
Getting started

Four steps. No code to write.

For the person who owns the archive: the deal team, corp dev, legal, the policy library. Your engineer or our forward-deployed team sets it up once.

  1. 1Step 1.

    Show it where the files are

    A shared folder, a Google Drive, a data room. Word, Excel, slides, PDFs, zips within zips.

  2. 2Step 2.

    Say what you're looking for

    One plain sentence about what the archive is for. It steers every reading and is stamped on every result.

  3. 3Step 3.

    See the price first

    A preview works out every step and what it will cost. Nothing is spent until you run it.

  4. 4Step 4.

    Get notes you can check

    Organised records, each finding tied to the page and line it came from, landed in Coconut or a folder.

beachcomb.yml
what your engineer sees
# Hello, corpus. The smallest useful pipeline: summarise each file, then
# write one overview from the summaries. Four files, three formats
# (CSV, DOCX, Markdown, plain text), two stages, one space.
#
#   comb run beachcomb.yml --dry-run              what would happen, no calls
#   comb run beachcomb.yml -e rehearsal --local   whole flow offline (mock models)
#   comb run beachcomb.yml --local                real models, pages to disk
#   comb run beachcomb.yml                        land in the space
name: hello-corpus

config:
  target: hello-corpus # a space you own; create it with `coco spaces` first

  sources:  
    corpus:
      type: local
      path: ./corpus

  models:  
    fast:
      provider: anthropic
      model: claude-haiku-5-5
      price: { input: 0.1, output: 0.5 }
    deep:
      provider: anthropic
      model: claude-opus-5-5
      price: { input: 4, output: 20 }

  receipt:
    path: "runs/{{ run.id }}"

  environments:
    rehearsal:
      models:
        fast: { provider: mock, model: mock }
        deep: { provider: mock, model: mock }

stages:  
  # One cheap call per file. {{ doc.text }} is the extracted text whatever
  # the format: a CSV as is, a DOCX as markdown with its tables.
  - name: summarize
    over: document
    model: fast
    promptFile: prompts/summarize.md
    land:  
      path: "summaries/{{ doc.slug }}"
      title: "Summary: {{ doc.name }}"
      metadata:
        source-file: "{{ doc.name }}"
        source-sha256: "{{ doc.sha256 }}"

  # One call over everything: the summaries from the stage above arrive as
  # {{ prev.summarize }}. The page is updated, not duplicated, on re-runs.
  - name: overview
    over: corpus
    model: deep
    promptFile: prompts/overview.md
    land:
      path: overview
      title: What the corpus says
      ifExists: update

The same four steps, as a file

  1. sources: where the files are.
  2. models: which reader at which pass: a cheap one for the look, a careful one for the read.
  3. stages: what each pass produces, and which files go on to the careful read.
  4. land: where the results go: pages and typed records in Coconut, or disk.

Commit it, review it like code, run it again next quarter.

The pipeline file
Price it first

Every run is priced before anything is spent.

01-hello-corpus $ comb run beachcomb.yml --dry-runexamples/01-hello-corpus · output trimmed
beachcomb 0.1.0 — hello-corpus
   examples/01-hello-corpus/beachcomb.yml

Sources
  corpus (local: ./corpus) — 4 document(s), ~552 tokens
    2026-10-15-support-sync.txt  621 chars  sha256 82911a26122c…
    release-notes-4.2.docx  531 chars  sha256 fa7830235a93…
    support-policy.md  558 chars  sha256 a1f5f6710781…
    support-tickets.csv  496 chars  sha256 9045e329d02b…
  no ledger yet — every document is new

summarize — over document × 4 · anthropic/claude-haiku-5-5
    4 call(s), ~847 input tokens, input cost under $0.01

overview — over corpus × 1 · anthropic/claude-opus-5-5
    1 call(s), ≥114 input tokens (plus upstream stage outputs), input cost under $0.01

 Would land
    hello-corpus/summaries/2026-10-15-support-sync
    hello-corpus/summaries/release-notes-4-2
    hello-corpus/summaries/support-policy
    hello-corpus/summaries/support-tickets
    hello-corpus/overview
    hello-corpus/runs/run-20261121T001120Z

Dry run ok — 4 document(s), 2 stage(s), 5 model call(s), ≥961 input tokens, 6 landing(s) planned. No model was called and nothing was written to Coconut.

No model was called and nothing was written to Coconut.

The first real run of the deal-archive example, on a 15-file synthetic PE corpus, 17 Nov 2026:

Model calls, first run
21
First run, 15 files
$0.63
Tokens in
31,807
Tokens out
36,862

Then the same pipeline again, with the ledger. Inventory and the close read reused all 20 units of work; only the roll-up, whose instructions changed, called a model.

StageModelCallsReusedTokens inTokens outCost
inventoryclaude-haiku-5-501500$0.00
extractclaude-opus-5-50500$0.00
deal-recordsclaude-opus-5-51010,25813,270$0.31
Three claims

Cheap, repeatable, incremental. Each one is a feature you can point at.

Plate II.Cheap

Cheap

A small model looks at every file’s first pages. A careful one reads only the few that matter. The preview prices it first.

headselectchunk--dry-runbudget caps
Plate III.Repeatable

Repeatable

One file describes the run. Goals are versioned into every output, each run leaves a receipt, every claim cites its source.

beachcomb.ymlgoals versionreceipt
Plate IV.Incremental

Incremental

A ledger keyed by content knows what is new, changed, moved or deleted. Unchanged work is reused; orphaned pages are flagged.

ledger.jsoncomb changesstale flags
Lands in Coconut

One holds what you know. The other is how it gets there.

coconut
where what you know lives, owned and reviewed
beachcomb
how a pile of documents gets there, and stays current

Coconut is the shared context layer where knowledge is owned, reviewed and served to people and agents over MCP. Beachcomb fills it from the archive you already have, and keeps it current as the archive changes.

Beachcomb runs without Coconut: --local writes pages to disk. Coconut adds versions, template-checked records, owners and review. We think that is where the output belongs, and we say so plainly.

deal-archive / beachcomb / run-20261117T182448Z / receipt
Run receipt
run
run-20261117T182448Z
goals version
5cc5c653e79d
corpus changes
0 new · 0 changed · 15 unchanged
status
completed
SOURCE-MANIFESTchangescorpus-mapdeals/*
Install

Three commands, beside your beachcomb.yml.

install
not published yet
$ npm install -g beachcomb
until then
from the monorepo
# not on npm yet. Until it is, from the monorepo:
$ git clone [public mirror URL] && cd [repo]
$ pnpm install && pnpm --filter beachcomb build
$ (cd packages/beachcomb && npm link)
run
$ comb validate beachcomb.yml
$ comb run beachcomb.yml --dry-run
$ comb run beachcomb.yml

Model keys go in a .env beside the pipeline. The real environment wins, and values are never printed.