Revibing BookWyrm is the practice of taking the existing BookWyrm codebase and bending it, with the help of agents and tools like Amp, into a lighter, more Hitchhiker-flavoured engine for a shared book commons. Instead of rewriting everything from scratch, revibing treats BookWyrm as a golden master. The running instance stays as a reference for behaviour and federation. The refactored sibling grows beside it, layer by layer, using automated refactors and tests to keep changes honest.
# Why BookWyrm BookWyrm is already a federated social reading platform. It speaks ActivityPub, knows about books, editions, shelves and reviews, and runs on a mainstream Django stack. For a project like Guide To Everything or a Bookshop Coop Store, this is a very good starting point. The domain is close to where we want to go. The stack is friendly to modern tooling and to Agentic Development. Revibing BookWyrm means keeping the useful spine. We keep the core ActivityPub objects, the reading flows and federation semantics. We then reshape names, modules and behaviours to match a new vibe and new governance.
# BookWyrm As Golden Master The first step in revibing BookWyrm is to set up a clean reference instance and leave it alone. This golden master runs the upstream code with minimal configuration changes. It is seeded with a few test users, some books, some shelves and simple interactions like follows and reviews. Agents and humans observe this instance from the outside. They record journeys through the UI, capture HTTP traffic for key actions, and document which ActivityPub messages flow in and out for common events like “add book to shelf” or “post a review”. The golden master becomes the behavioural specification. The refactored sibling is judged by how well it can reproduce or intentionally diverge from this behaviour.
# Spec First, Then Amp Revibing BookWyrm works best with a spec-first rhythm. Short specs are written in wiki pages for each change. A spec might say, “Rename Review to GuideNote in the internal model, but keep external ActivityPub objects compatible” or “Extract notifications into a clearer module without changing what users see”. These specs give Amp and other agents something concrete to aim at. Amp is asked to implement the spec as a branch. It updates models, views, serializers and tests to reflect the new structure. Humans review the resulting pull request. They compare it with the spec and with the behaviour of the golden master. Only once the change is understood and tested is it merged into the revibed sibling.
# Easy Wins In Revibing BookWyrm There are parts of BookWyrm that revibe very smoothly. Renaming concepts across the codebase is straightforward. With whole-repo understanding, an agent can chase every occurrence of a model or field, adjust imports, update templates and fix tests. Extracting duplicated patterns into helpers is also simple. Notification sending, ActivityPub wrapping and common query patterns can be moved into clearer modules with automated refactors, shrinking view functions and tasks without changing behaviour. Frontend clean-ups and template refactors are good early targets. Amp can help split large templates into smaller partials, simplify forms, and align naming with new concepts like “Guides”, “Orbits” or “Improbability Events” while keeping the HTML structure recognisable. These easy wins reduce friction for future changes. They make the codebase easier to hold in an agent’s context window and easier for humans to reason about.
# Hard Edges In Revibing BookWyrm Some parts of BookWyrm resist casual revibing. ActivityPub federation is delicate. Privacy scopes, inbox routing and signature handling are all intertwined. Automated refactors must tread carefully, with strong tests and a clear understanding of how local actions translate into remote messages. Database-heavy flows are also sensitive. Timeline queries, complex filters and denormalised counters can be disrupted by well-meaning refactors. Without realistic data and performance checks, a revibe can make everything slower or less reliable. Implicit business rules are hidden in corners. Old flags, legacy migrations, and historical behaviour quirks matter to existing instances. Agents can move code around, but they do not automatically understand why a rule exists. These hard edges call for human review, golden-master comparisons and incremental changes. They are not places to let an agent run unattended.
# Towards A Hitchhiker Node The goal of revibing BookWyrm is not to escape BookWyrm. It is to grow a sibling that fits better into a wider commons. That sibling might treat “Guides” and “Improbability Events” as first-class objects alongside books. It might add bookshop-level entities and stock awareness for a Bookshop Coop Store. It might support “pocket edition” bundles that line up with the Guide To Everything. By revibing rather than rewriting, we inherit years of work on reading flows and federation. We keep the link to the broader Fediverse while gradually bending the internals towards a new tone, new governance and new collaborative patterns. Revibing BookWyrm in this way is a concrete example of Revibing as a practice. It shows how an existing, successful commons app can be adapted to serve new communities, using agents as refactor engines rather than as replacements for human judgement.
# See
- joinbookwyrm.com 
- github.com