On Writing in a Repository

2025– — essay

Every screenwriter I know keeps a bible. Not in any organized way — usually a Google Doc or a notebook, sometimes a folder of files, sometimes literally a binder. Inside lives the canonical version of what has been established about the story: who the characters are, where things take place, what is true. The bible is the source of truth. The script is the place where the story actually happens. When the two disagree, you have a problem.

Writers have been keeping bibles for as long as there have been long stories to write, and the procedure for keeping them in sync with the script has always been the same: discipline. You change something in the script, you update the bible. You discover something new about a character, you write it into the bible. You realize the timeline doesn't work, you fix it in both places. It works as well as your discipline, which means usually it stops working around the third draft.

This is the kind of problem I have spent fifteen years watching software people solve.

I came to writing through documentary, which has its own version of the bible — the assembly, the working cut, plus all the notes and timelines and continuity binders that surround it. But documentary is collaborative by nature, so the discipline of keeping things in sync gets distributed across a team. In narrative screenwriting, especially when one person is doing it alone, the discipline concentrates into a single skull, and skulls have known limits.

Around the time I started writing my own screenplays, I had also been spending more and more time inside programmer tooling — Git, Markdown, structured directories, AI assistants that could read an entire repository and reason about it. I noticed something that, in retrospect, was obvious. Programmers have spent decades building tools for exactly the problem screenwriters complain about: managing complex, evolving documents where a canonical reference and a working draft have to stay in conversation, with branches for exploring alternatives, commits for marking decisions, diffs for seeing what changed.

The tools were not designed for screenplays. But the underlying problems they solve are not really about code. They are about how to handle complexity when many things are changing at once and you cannot hold them all in your head.

I started moving my writing into Git.

The shape that emerged, over a few months of trying things and throwing things away, looks like this. There is a repository. Inside it there is a bible directory that holds the canonical reference — the world, the theme, the rules. There is a characters directory with one file per major character. There is a locations directory. There is a beats directory with the structural skeleton. There is a scenes directory where the actual screenplay material lives, one scene per file. And there is a single assembled script file that gets generated from the scenes.

Everything except the actual screenplay material is in Markdown. The screenplay itself is in Fountain, a plain-text format for screenplays that has been around since 2012 and is the closest the screenwriting world has gotten to a real interchange standard. The split matters: Markdown reads cleanly on a phone, on GitHub's web view, in any text editor; Fountain handles scene headings, dialogue, and action description with the formatting screenplays require. Each format does the job it was designed for.

The rules of engagement turn out to be the interesting part. Some of them are translations from software practice that work well in writing. Every session ends with a commit, and the commit message says what changed, what was decided, what is still open. When you're exploring a major alternative — a different ending, a different protagonist, a different tonal register — you make a branch, let the alternative live until you decide, then merge or throw away. One scene per file, because it is easier to diff, easier to reorder, easier to throw away.

Some rules are specific to writing and don't have software equivalents. The bible is canonical: if a scene contradicts the bible, you either update the bible or fix the scene; you never let them silently drift. Questions before decisions, decisions before drafting: when something surfaces mid-draft that you don't have an answer to, you write it into an open-questions file rather than drafting past it. The rule is simple — you cannot write a good scene that depends on a decision you haven't made.

None of this is revolutionary on its own. Programmers have been doing all of these things for decades. What's interesting is not the practices but where they came from. The attitudes encoded in software tooling — make change discrete, make decisions legible, separate canonical from working — have been hard-won over fifty years of professional software development, and they turn out to apply to creative writing more than I would have predicted before trying.

The other piece, the part I am most curious about, is what role the AI plays.

The default assumption right now is that AI in creative writing means an AI that generates content — writes the next sentence, drafts the next scene, suggests the next line of dialogue. I am not particularly interested in that. The hard thing about screenwriting isn't generating sentences. The hard thing is keeping track of what is true, noticing when something contradicts what you established forty pages ago, holding the whole shape of the story in working memory while you make a small decision about a single beat.

That is what AI is good at, and what humans are bad at.

When I open a session, the model reads the relevant part of the repo — the synopsis, the open questions, the bible files for whatever is in focus, the scenes that touch the current work. It is not generating; it is holding. It can answer questions like did we ever establish what the protagonist did before the war, or is that still open? and the line you just wrote in scene fourteen contradicts what the captain said in scene seven, do you want to fix one or change the bible? That kind of help is unglamorous and constant, and it removes a kind of cognitive overhead that has, for as long as people have been writing long stories, sat squarely on the writer's shoulders.

What this means in practice is that the AI is functioning as a continuity person. In film production, continuity is a real role on a real set — somebody whose job is to make sure the prop on the table in shot three is in the same position in shot four. Continuity in writing has never been a role, because it couldn't be — there was no way to share the text with a continuity person efficiently enough for them to catch contradictions in real time. Now there is. The continuity person is in the repo with you.

I don't know yet how much of this will hold up. The work is research, not a finished methodology — things change every couple of months as I figure out what works. The current shape may not survive its first encounter with a serious collaborator, and one of the things I'm most curious to find out is what happens when more than one writer is in the repo. Will the branching model that programmers use for parallel development map cleanly onto two writers exploring different versions of the third act? I genuinely don't know. The literature on collaborative software development is rich; the literature on collaborative creative writing is mostly anecdotal. There may be lessons in one for the other, or there may not.

I am also aware that there is something slightly absurd about a screenwriter using a tool designed for kernel developers. Some of the friction is unavoidable — Git is not actually trying to be friendly, and writers should not have to learn to rebase. The version of this that eventually makes sense for working writers is probably not the raw infrastructure I am using now. It is a thing built on top of it, that hides the parts that don't serve writing and surfaces the parts that do. ScriptHub, for the moment, is the raw infrastructure. The thing built on top is somewhere in the future.

But the underlying observation — that programmers have spent decades figuring out how to manage complex, evolving creative work, and that some of what they figured out is the kind of thing screenwriters have always needed and have always done badly — feels solid to me. Solid enough to keep going.

That is what ScriptHub is for. It is one writer's experiment in seeing what carries across.