Authorbot

Authorbot manages authorship without pretending to be an author. It never calls a language model. Humans and external agents write and edit the prose; Authorbot keeps the chapters, comments, decisions, assignments, attribution, revisions, and published site tied together through Git.

It started as the machinery behind The Causal Projector and grew into something another person can install from npm (@authorbot/create and the authorbot CLI are both published). The core project is done: it’s v0.1 software and I expect bugs, but what’s left is maintenance and whatever I learn from other authors using it. Releases auto-publish to GitHub now, so the registry and the repo stay in sync.

How it’s put together

The durable source of truth is a normal Git repository. Chapters are Markdown; story notes and other long-lived records are readable files. If Authorbot disappears, the book doesn’t become an archaeological dig through an abandoned SaaS database.

A database handles the live parts Git is lousy at: sessions, scoped agent tokens, annotations, votes, leases, and the work queue. It’s a projection and can be rebuilt from the repository. The API is the only write path, so humans and agents get the same validation and attribution rules.

The reading site starts as plain HTML. Turn collaboration on and a reader can select a sentence, leave an anchored note, reply, and vote. An author can promote that discussion to work, an agent can claim it with a lease, and the accepted revision lands in Git as one attributed commit. There’s no hidden model call anywhere in that loop: Authorbot doesn’t silently rewrite a chapter, it coordinates the people and tools doing the work.

Hosted and offline

Hosted mode runs the site, API, D1 database, and GitHub writer on Cloudflare. npx @authorbot/create walks through five stages (environment checks, the book repository, the reading site, collaboration, and an agent invite), and you can stop after any of them: a solo writer can quit early and use it as a plain Git-backed publisher. It also has unpublish and teardown commands, because a setup tool that creates cloud resources without knowing how to remove them is how every terrible dashboard begins.

npx authorbot dev is the offline version: a managed branch and worktree, the real API against private SQLite, and the same browser UI on 127.0.0.1. Browser and agent writes still become narrow attributed commits, and once the packages are installed the whole authoring loop works without GitHub, Cloudflare, or a network connection. Local sessions can validate the book and open a draft pull request, but they can’t merge or deploy on their own.

Agents are guests, not authors

Agents install the collaborator skill with npx skills add JoeMattie/authorbot. It teaches the contribution loop, the API, and the safety rules, and it ships drafter, critic, continuity, and reviewer roles. An agent gets a scoped token with exact permissions, claims work through the API, and submits a draft for review. It never gets direct GitHub write access, and it can’t manufacture a vote from another agent into human approval.

What the build looked like

The repository went from first commit to a usable release in about 100 hours: 195 commits and roughly 175,000 physical lines of code (about 100,000 of product and 74,000 of tests) at the last clean tag, with 306 subagent transcripts in the log directory. I directed the product, wrote the contracts, and made the ugly boundary calls; Claude and Codex did a ridiculous amount of the construction. At standard API rates the recorded model calls would have cost about $3,357. My actual out-of-pocket was around $55 in prorated subscriptions. The writeup below has the full accounting, including why those two numbers are so far apart.

The proving ground is The Causal Projector, the book Authorbot was built for, which is a much better test than another perfect sample book nobody cares about.

Updates