{examples.map((e, i) => )}

{ex.file}

setHover(null)}>

Code

						{ex.code.map((segs, i) =>  setHover({
    side: "code",
    n: i + 1
  })}>
								{i + 1}
								
									{segs.map(([k, t], j) => 
											{t}
										)}
									{segs.length === 0 ? " " : null}
								
							)}

English

{ex.english.map((l, i) => l === null ?

setHover({ side: "english", i })}> {l.s.map(([k, t], j) => {t} )}

)}

Generated by Narrator from the code on the left. Hover a line to see where it came from.

; };

Read code in plain English

Narrator turns TypeScript and JavaScript into clear sentences, deterministically and without an LLM. It runs on your server or in the browser.

Get started Browser extension

## What it is Narrator is an SDK, published under the `@usenarrator/*` scope, that turns source files and diffs into English sentences. Every phrase comes from a syntax node and a rule, so the same code always reads the same way, and you can point at the rule that produced any sentence. Narrator uses rules, not a language model, so the same code always produces the same English. It is fast enough to narrate a whole pull request when the page loads. It uses the native oxc parser on Node and Bun, and a WASM build of the same parser in browsers, extension workers and edge runtimes. You can add source languages (TypeScript and JavaScript today), output languages (English today), and library plugins. Twenty-five ship today, from React and Next.js to Drizzle, Stripe and Temporal. ## Why it exists More and more code is written quickly, often with help from AI tools, and someone still has to review it. Reading a diff line by line is slow, and a summary written by a model can sound right while missing the one condition that matters. Narrator sits between the two. It reads every statement, so nothing is skipped, and it says what the code does in sentences you can skim. When the English looks wrong, the code usually is too. It also helps people who read code less often than they write it: a product manager checking what a pricing rule really does, a new teammate finding their way around, or a reviewer working in a library they don't know well. ## A 30-second demo The `narrator` CLI narrates files, directories and git diffs. Point it at a file: ```ts billing.ts theme={null} export async function renewSubscription(subscription: Subscription, now: Date) { if (subscription.status === "canceled") return; const plan = plans.find((p) => p.id === subscription.planId); if (!plan) throw new NotFoundError("Unknown plan"); for (const seat of subscription.seats) { if (seat.expiresAt < now) await releaseSeat(seat); } await sendReceipt({ to: subscription.ownerEmail, amount: plan.price }); } ``` ```text narrator billing.ts --plain theme={null} To renew subscription (async), given subscription (Subscription) and now (Date): If subscription's status is "canceled", stop here. Let plan be the first p in plans where p's ID is subscription's plan ID. If plan is missing, fail with a not found error: "Unknown plan". For each seat in subscription's seats: If seat's expires at is before now, release seat (seat). Send receipt (to: subscription's owner email and amount: plan's price). ``` A few things to notice: `ownerEmail` became "owner email" (identifiers are split into words, and abbreviations expand through a glossary), the `find` callback became "the first p in plans where…", and the guard clause became a single "If …, stop here." Nothing was summarized away, because Narrator narrates every statement instead of paraphrasing the whole function. ## Reading diffs on GitHub The browser extension uses the same engine to replace GitHub's diff rows with English, so you can review what a pull request does before you read how it does it. A GitHub pull request diff where the code rows have been replaced by English sentences

A GitHub pull request diff where the code rows have been replaced by English sentences

## Where to go next Narrate a file and a diff from your own code in five minutes. Follow a statement from source code through the engine and plugins to the finished sentence. Read GitHub pull requests in English, inline, in either split or unified view. Add plugins so that calls to your libraries read naturally. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.