AuthorshipA place to write a novel inside VS Code. Your manuscript stays a file — markdown, in your own repository, with your own history. Authorship adds an editor that understands what a story is made of, a reader that tells you what is wrong with a passage, and a way out to an EPUB. Authorship is meant to run entirely on your machine, and that is where it is heading. Not every machine has the memory its models need, though, so for now the heavier work is done on a backend we host ourselves: open-weight models, on our own hardware, kept private. See Privacy.
Contents
What it needs
Nothing but that environment is downloaded: the models need more memory than the machines most of us write on have, so they are served from hardware that has it. Writing, exporting and publishing ask nothing of them, and work whether the backend is reachable or not. First runThe first time Authorship starts after an install or an update, it builds the Python environment its models run in. This is a download of a few gigabytes and takes a few minutes on a cold machine. It happens once per version, in the background, with a notification saying how it is getting on — VS Code stays usable throughout, and the editor works before it has finished. Everything it installs goes into the extension's own storage — its own copy of
Python, its own packages, its own cache. Nothing is written into your project,
and nothing is put on your If anything goes wrong, the whole story is in the Authorship output channel (View › Output, then pick Authorship from the dropdown). Starting a storyA story lives in a Start empty. Make a new file called Bring a manuscript you already have. Open a
The editorA
Nothing is drawn over anything else: each of the three has room of its own.
Editing. Double-click a section — or select it and press Where you are. The line at the top of the toolbar names the part and chapter you are reading, taken from what is on screen rather than from what you last clicked — scroll through a hundred thousand words and it keeps up. The word count sits at the other end. What it weighs. Every chapter says in its footer how many words are written under it, and every part says what its chapters weigh together. The same count as the toolbar's, made of the same words — the prose and nothing else, so a title you rename and a note you leave yourself weigh nothing in either. Both keep up with the keys rather than with the file. Folding. Folding a section takes away its body and its footer and leaves its header exactly as it was — the same name, in the same place, saying the same thing. A folded document is the headers of its sections and nothing else. Splitting and joining. Hover between two paragraphs and a line appears at the nearest seam, with a button on it. Press it to cut the section in two there, or — at the seam above a section — to join it to the one before.
Adding, moving, removing. The strip in the gap between two sections adds
one there, which is nearly always what "add a chapter" means: a button each for
the kinds you reach for while writing — Markdown, Chapter, Note, Part — and a
Find and replace.
Several cursors. Select a word and press
The file underneath. View Source in the toolbar opens the same file as plain text, in VS Code's own markdown editor. It is the same document — edits in either show up in the other, and git sees one file, not two.
SectionsA section's kind is what it is, and it is never guessed from what it says: a chapter called "Disclaimer" is still a chapter.
Sections with fields — a title page, a chapter, an about page — show them as labelled boxes rather than as prose you have to remember the shape of.
The order on the page is the order in the book. Move the disclaimer above the title page here and it is above it in the EPUB; there is no second list of front matter to keep in step. The pages you write onceThree of the pages above are the same in every book you write and different for every author who writes one: the disclaimer, the About the Author page, and the name and publisher on a title page. Authorship has no words of its own for any of them, and does not want any — a disclaimer shipped with an editor is that editor's opinion of what a story warns its readers about, and it would be the wrong opinion for somebody. So these pages are yours, kept per workspace in
which Authorship writes — empty — the first time you open a story in a folder that has none. Fill it in once, and every disclaimer, author page and title page you add from then on starts from what you wrote. Leave it alone and those sections are simply added blank, for you to write in the editor as you would any other.
It is a file in your repository, so the templates travel with the stories and their history is your history — not a preference on one machine. A page of prose is a list of lines rather than one string, because JSON has no multi-line string and a disclaimer kept as one is a disclaimer nobody wants to edit. This way it also diffs a line at a time. One plain string works too, if you would rather write one. Anything you leave empty is left out of the section entirely: a title page in a workspace with no publisher is added with no publisher field, not with a blank one to read past. Edits take effect as you save them; there is no need to reopen a story. A file that is not valid JSON is reported once and then ignored, so a half-finished edit never silently changes what a page says. A story opened from outside a workspace has nowhere to keep templates, and starts these pages empty. Checking the proseNothing is checked until you ask. Drafting is the other half of writing, and an opinion arriving mid-sentence is an opinion nobody wanted. Press Check Prose in the toolbar and Authorship reads the whole document once, then re-reads each paragraph as you finish writing it.
Two passes run: a set of rules that answers in milliseconds, and a grammar model that takes a few seconds. The rules draw first and the model adds to what they put up, so you are never waiting on the slowest thing in the report. What the rules look for
Stopping on a mark. Hover an underline and a box says what is wrong and why. Where the rule already knows what belongs there, the replacement is offered outright. Where it does not, the Fix button asks the model for one — it rewrites the marked phrase only, in your tense and register, and the fix is thrown away unless the rule that found the fault agrees it is gone. Marks live for as long as the editor is open and are written nowhere. What a check thinks of your prose is not part of your prose. Writing a blurbGenerative AI disclosure: this functionality uses an AI model, served from the backend rather than from your machine, to create a draft of the blurb. It is highly advised to treat the generated blurb as a working draft rather than a finished section. Add a Blurb section and press the run button in the column beside it. The model reads the book the way a reader reads it — the first chapter, then each chapter after it with the blurb so far — and what comes back at the end is the blurb the story has earned. Nothing has to hold the whole manuscript at once, so this works on a novel and not only on a short story. The bar counts chapters, because that is the division the work actually has. You can go on writing elsewhere while it reads, and the square button stops it.
The blurb is written from the story alone: the notes in your margin, the scaffolding of the format and any blurb already there are all kept out of it. It is copy for a shop listing, so it is not printed in the book. The story so farGenerative AI disclosure: this functionality uses an AI model, served from the backend rather than from your machine, to create a draft of the recap. It is highly advised to treat the generated recap as a working draft rather than a finished section. The blurb's near relation, for a serial. Add a The Story So Far section, write the earlier documents into its Documents box — separated by commas, named the way they sit beside this one — and press the run button beside it.
They are read in alphabetical order — with numbers read as numbers, so
The reading is the same as a blurb's: a chapter at a time, with the recap so far carried between them, so a shelf of finished volumes is no harder than one. The bar counts the chapters of all of them together, you can go on writing while it reads, and the square button stops it. The paths are written relative to the document, so a story that is moved, cloned or opened on another machine still finds its earlier volumes. Like the blurb, this is written beside the story rather than in it: it is not printed in the book and not counted in the word count, and it is yours to edit once it lands. Fixing style and grammarGenerative AI disclosure: this one rewrites your prose, with a model far too large to sit beside your editor, so the chapters of the document it is run on go to the backend that serves it. Read Privacy before you use it, and treat what comes back as an edit to review rather than an edit to accept. Fix Style & Grammar — the sparkle in the toolbar, next to Check Prose — reads the whole manuscript and corrects it, a chapter at a time. Where a check underlines what it thinks is wrong and leaves the prose alone, this rewrites it: clumsy sentences, wrong words, tangled clauses, punctuation. It works a chapter at a time and each chapter goes to the model with every chapter already corrected in front of it — so the second half of the book is edited towards the first half as this pass left it, and a name spelt one way in chapter one is spelt that way in chapter forty. That context is the reason this tool runs where it does: no model small enough to run on a laptop can hold a novel while it reads. A bar under the toolbar counts the chapters, and the square button stops it. The
manuscript is locked while it runs — every section is about to be replaced in
turn — and each chapter's corrections land as they come back, so a pass you stop
halfway leaves the chapters it finished corrected. It all lands as ordinary
edits: A chapter is only written back if what came back is plausibly that chapter: about as long as it went in, ending where a sentence ends, and in the same number of sections it was cut into. Anything else — a model that ran out of room, that stopped against a filter, that summarised instead of edited — is thrown away and the chapter is left exactly as you wrote it. Authorship says afterwards which chapters those were and why, because a chapter left alone looks in the document exactly like a chapter that needed nothing. Only the story goes: the chapters' titles and the markdown written under them. Your notes, the blurb, the cover, the title page and the table of contents stay here — they are about the book rather than in it. Which model corrects itThere is nothing to sign in to and no model to choose: which model serves which tool is the backend's business, and the Authorship sidebar names the ones it is serving and whether each of them is up. A pass that cannot reach its model stops with the message the server gave, and the chapters it had already corrected stay corrected. Building the bookRun All builds every section that is built rather than written — today that is the table of contents, made from the chapters around it in an instant. A built section whose source has moved on says so in the column beside it, so you can see at a glance what is stale. Export EPUB binds the book beside the document. Everything it needs is in the document itself — the title page names and credits it, the cover section points at the art, the contents section asks for a table of contents, the chapters are the story, and the disclaimer and about pages open and close it. Notes and the blurb stay out. There is no second file carrying half the answer. A book that is not ready is not bound. Ask for the export and the answer is either the file or what is standing in the way of it: sections that are missing, sections a reader would not find where they are, and sections that are there with nothing in them. That last one is worth saying plainly — adding a title page does not give a book a title, and a cover pointing at art nobody has drawn is no more a cover than none at all. The five the book waits for are Cover, Title Page, Table of Contents and Blurb opening the document, and About the Author closing it. Fix lays the sections out — writing in what is absent, moving what is out of place, and leaving everything you wrote exactly as you wrote it — then marks in red what is still to write and stops. No book is bound. Export Anyway binds what is there, because it is your book and you have been shown what is missing. A fix goes in as one edit, so a single undo takes it back out, and the marks lift at the next export that finds those sections written. All of that is decided where the book is bound, in
Export Markdown writes the document out as one plain markdown manuscript —
Dividing a long story into partsDivide into Parts cuts the story into Where a story breaks is a question about the story, so it is answered in the story. A Part you want the reader to meet — the tale, in a book of tales — is printed as a page of its own and divides the files as well. A Part that is only there to say "break here" is marked unprinted: untick Printed on it, and it divides the files while the book goes out with no page where it stands. A story with no Parts at all is asking to be divided nowhere, and is left alone. Each part is a story document like any other: it carries the book's furniture, its title page renumbered, and its share of the chapters — and it opens in this editor and exports to an EPUB by the same buttons. A file cut at an unprinted Part inside "Day One" is still titled Veriona — Day One — Part 2.
The Authorship sidebarThe Authorship icon in the activity bar opens the Manuscript view, which reports on the machinery rather than on the book: which models the backend is serving and what state each of them is in — deploying, running, stopped — and what work the server has in hand. A running job can be stopped from here.
The status bar
The file formatA
Three things follow from that, and they are the reason for it: Every markdown reader renders it. The markers are comments, so GitHub, your static site, and the preview pane all show the story and none of the scaffolding. Plain markdown is already a story document. A file with no markers reads as one prose section holding the lot. Nothing you have written is locked out. Nothing is lost to a version that does not understand it. A section kind this editor has never heard of is carried through untouched, so a document written by hand, or by a newer version, survives a round trip through an older one. And because the file is text and the editor edits the text, git behaves: a diff
of a chapter is a diff of that chapter,
Keyboard
CommandsEvery toolbar button is also a command, so it is in the Command Palette
(
PrivacyWhere this is going. The goal is an Authorship that runs entirely on your machine. The models worth using need more memory than most machines have, so for now they are served from a backend we host ourselves — open-weight models on our own hardware. Your manuscript goes there and no further. One of them is not ours yet: fixing the style is still served by Google's Gemini API, through the backend and on the backend's own account, and that goes when the open-weight model that replaces it is in. The editor is yours alone. Writing, importing and exporting markdown, building
the table of contents, dividing a story into parts, exporting the EPUB and the
rules half of the prose check all happen in VS Code and in the server the
extension starts on What sends prose is what asks a model: fixing the style, the grammar half of the prose check, writing a blurb, writing the story so far, and identifying the plots. Each of them sends the story and nothing else — the chapters' titles and the markdown written under them, and for the story so far those of the earlier volumes you name. Your notes, the blurb, the cover, the title page and the table of contents stay here; they are about the book rather than in it. Nothing is sent until you press the button that starts it. There is no API key in your editor, in your settings or in your keychain. Whatever credentials the models need are the backend's own, and nothing about your account goes from here. TroubleshootingThe status bar says The first run is taking a long time. It is downloading a Python interpreter and several gigabytes of packages. The notification shows the line the installer is on; the output channel shows all of them. It happens once per version. A check found nothing. Checks are off until you press Check Prose. If they are on and nothing is underlined, look at the status bar: the first check after a start has to load a model, and the models are large. A pass stopped with a message from the server. The message is repeated as it came: a model that is not up yet, a model that refused the chapter, or a backend that would not answer. The Serving Status drawer in the sidebar says which models are running. Whatever the pass had already corrected stays corrected, so running it again picks up from a book that is part-way edited rather than starting from nothing. A chapter came back unchanged. The pass refuses an answer that is not plausibly the chapter — too short, too long, cut off mid-sentence, or in the wrong number of sections — and leaves your text alone rather than putting a fragment in the document. The message at the end names the chapters and the reason. Running it again often settles it; a chapter that fails repeatedly is usually one long enough to exhaust the model's output budget. Fixing the style left a chapter untouched. A chapter is often several sections, and they have to come back as the same several. When the model runs them together the chapter cannot be put back where it came from, so it is left exactly as you wrote it rather than have its seams moved for you. Running the pass again usually settles it. Export failed. Exporting an EPUB is done by the local server, so it needs
the server up — see Two windows, one server. The first VS Code window to start the server serves
every window after it. Closing that window stops the server, and the windows
left behind read Reporting a problemPlease open an issue at github.com/robodatalab/writer, with what the Authorship output channel said if the extension itself misbehaved. |

















