Questions people ask
Short answers. Every one of them is checkable.
What is Storyteller?#
A zero-dependency TypeScript logging library. You report beats of work as they happen; when the work is done, finish() emits one structured JSON record that tells the whole story — who did it, what happened in order, how long it took, how it ended. Optionally, each beat streams live as it happens.
Does it really have zero dependencies?#
Yes. npm install @lovelaces-io/storyteller installs one package and nothing else. For comparison, winston and pino each declare 11 direct dependencies. Check any of these with npm view <package> dependencies.
How is it different from pino or winston?#
Those are line loggers: every call produces one line, and reconstructing what happened means correlating many lines afterwards. Storyteller’s unit is the story — one record per operation, with the beats inside it, in order. It is closer to a trace than a log, but with human-readable semantics and no collector to run. Pino is faster at raw line throughput; if you need a million lines a second, use pino. If you need to know what happened, one operation at a time, use this.
Is it for AI agents or for people?#
Both, and that is the point. An agent’s automated run and a developer’s manual debugging session produce the same record in the same shape, so one question — “what happened to billing yesterday?” — returns both. Agents get npx @lovelaces-io/storyteller init, a guidance block for AGENTS.md, llms.txt, and NDJSON output. People get live narration in the terminal and a readable report.
Does it work in the browser?#
The core does — it has no Node-only imports and guards every process access. The console audience uses %c styling in browsers. The storyteller init CLI and the NDJSON audience’s stdout default are Node-only.
What does it cost?#
Nothing. MIT licensed, free forever, including for commercial use. There is no hosted service and no paid tier.
Is the old tell() / warn() / oops() API going away?#
Deprecated in 0.3, removed at 1.0. They still work identically in the meantime. Use finish(title, { level }) and report() for new code; see migrating from 0.2.
Can I send stories to Discord, Slack, or my database?#
Yes — an audience is an object with a name and a hear function. A Discord webhook audience is about fifteen lines; see Audiences. A database audience is built in.