Getting started

Install it, report a few beats of work, finish the story, and look at what came out. Two minutes.

Install#

One command sets a project up: it installs the package, writes a configured storyteller, and adds a short guide to your AGENTS.md so any agent working in the repo knows how to use it.

$ npx @lovelaces-io/storyteller init

Safe to run again later — it never overwrites anything you've edited. Or just install the package and wire it up yourself:

$ npm install @lovelaces-io/storyteller

Your first story#

Report each beat as it happens. When the work is done, finish. Everything you reported becomes one record.

app.ts 
import { Storyteller } from "@lovelaces-io/storyteller";

const story = new Storyteller({
  origin: { who: "my-service" },
});

story.report("User clicked checkout");
story.report("Cart validated", { what: { items: 3 } });
story.finish("Checkout started");

report() takes a message, or any value at all — an error, an API response, a Map. finish() takes a title and, optionally, a level and an error.

What comes out#

The console prints a readable report by default. Underneath is a clean JSON record you can store anywhere:

JSON.stringify(event) 
{
  "timestamp": "2026-03-31T14:30:00.000Z",
  "level": "Information",
  "title": "Checkout started",
  "origin": { "who": "my-service" },
  "durationMs": 0,
  "notes": [
    { "timestamp": "...", "note": "User clicked checkout" },
    { "timestamp": "...", "note": "Cart validated", "what": { "items": 3 } }
  ]
}

That's the whole story, in one place: what happened, in order, how long it took, who did it, and how it ended.

Two shapes, one story#

Story — JSON

What you store. Database, log file, monitoring, an agent's memory. JSON.stringify(event) is the complete row.

Report — text

What you read. Console, terminal, a Discord message. formatStory(event) or event.summarize().

Keep these separate in your head. Storage audiences get the record; people get the report. Never store the formatted text.

Where next#

Hand this to an agent Open in Claude Open in ChatGPT