builderbot: a hub page, three version tools, and a root manifest five patches behind

The whole page is a paragraph, one command and a course link

Count what is actually on the front page. A centred logo, two badges, one paragraph of capability claims, one command, a link to the hosted documentation, a link to a paid course, and two ways to get in touch. There is no installation section beyond the single command, no configuration, no example, no API surface. The paragraph is therefore the entire design statement, and it is worth quoting its shape rather than its adjectives: you can build automated conversation flows that are agnostic to the WhatsApp provider, set up automated responses for frequently asked questions, receive and respond to messages automatically, track interactions with customers, and set up triggers to extend the functionality. Read the first clause against the rest of the project and the shape becomes clear. The abstraction is real in the design and absent everywhere else: the published package name, the repository title, the four keywords and the course pitch are all one platform. The scaffolding command itself is the fastest thing on the page:

npm create builderbot@latest

Three version tools and one number nobody can point at

The root manifest declares a version, and it is behind. It says 1.3.10 while the newest release tag in the tag list is 1.3.15, and the root package is marked private, so its number was never meant to be the published one. That would be a footnote if the canonical number lived somewhere clear. It does not. There is a separate script whose whole job is to generate a release summary by reading the version out of the Lerna configuration file, which makes that file the source of truth for releases. There is a version-bump script that runs a workspace dependency check and then forces a version across every package with Lerna. And there is a release script that invokes a conventional changelog generator with both a prerelease flag and a global flag, a combination that rewrites the changelog and tags across the whole repository rather than one package. Three tools writing one number, with the manifest not participating and the published package named differently again.

The preinstall hook fetches a package to check which package manager you used

One line in the manifest is worth its own section. Before anything installs, the preinstall hook runs the package fetcher to execute a tool whose entire purpose is to abort the install if the package manager is not the expected one. The pattern is common and the intent is good, since a monorepo built around one package manager really does break under another. The awkwardness is that the enforcement mechanism itself needs the registry and a package runner before the package manager has been validated. It also runs on every install of the workspace, including inside container images and continuous integration environments where a package runner may not be installed at all, which is exactly where you least want an install to fail on a policy check. None of this is fatal. It is, though, the kind of line that produces a confusing failure on a machine you did not configure, and the cost of removing it is small.

Two monorepo orchestrators and a workspace file, all answering the same question

The root carries three files that all claim to describe the shape of the workspace: a Lerna configuration, an Nx configuration, and a pnpm workspace file. Two of those are monorepo orchestrators, and the scripts lean on Lerna directly for building, testing, versioning and publishing. Publishing is split three ways as well: a canary publish that takes versions from each package rather than from the root, a publish that tags development builds, and a separate script that checks workspace dependencies before a version bump. That last one is the tell. A project does not write a dependency-consistency check across its own packages unless it has been bitten by workspace drift, which is what you would expect when two orchestrators are present and a third file also declares the workspace. Nothing here is broken and the layering may well be deliberate, with one tool used for publishing and another for task graph caching. But a new contributor has to work out which tool owns the topology before their first change, and the page offers no help on that.

A Finder metadata file and a generated lint report are both under version control

The root directory contains a macOS Finder metadata file. That is the classic evidence of at least one commit made through a desktop file browser rather than the command line, and it is harmless on its own. Beside it sits a generated lint report as a committed file rather than something a build produces and an archive stores. Both are individually trivial and jointly corrosive, because what they teach a new contributor is that generated output belongs in the repository. Around them the hygiene is genuinely mixed. There is a to-do document committed next to the readme, two agent instruction files for two different assistants, an editor directory, a coverage tool configuration, both a modern flat linter configuration and a legacy ignore file, and a formatter with its own configuration and ignore list, plus git hooks installed from the manifest's prepare step. Somebody is maintaining a lot of small files, and the two that should not be tracked are.

Four directories in the tree that the page never mentions

There is a starters directory, which is almost certainly where the templates for the create command live and which no page text refers to, so the first thing a new user does runs code they have not been shown. There is a documentation directory that the page does not link to, since the page points only at the hosted site, so you cannot tell whether it is the source of that site or something separate. There is a directory with no extension at all whose name reads like reference material for the messaging calls the library makes, which is the kind of file that is invaluable to a maintainer and invisible to a user. And there is a small configuration directory at the top level. Four places where the implementation lives, none of them mapped from the front page, in a project whose entire pitch is that you can read the documentation and see how it works. None of these is a criticism of the code. It is a criticism of the page, which is a business card.

The package you install and the package in the repository have different names

The repository's root package is scoped to the organisation, marked private, and its main field points at an application file that is not in the tree at all. The package a user installs from the registry sits under the same scope with a different name, and the version badge on the page points at that published one, which is the only place the two are reconciled. The command line interface is a third package with its own binary entry, invoked through a script in the manifest. So the first thing anyone does, running the create command, lands in a workspace whose root version field is five patches behind the release they are actually on, and the connection between the three names is a line of prose. None of that will stop you. It is the kind of detail that costs an afternoon the first time and then becomes something you stop noticing, which is a reasonable trade for a project this size and an annoying one to document around.

Editorial conclusion

Use this if you are building automated conversations on a messaging platform and you want a scaffolder rather than a platform, and read the two claims on the page closely before you commit. The provider-independence claim is the interesting one, because it is the one place the design and the branding disagree. The second is that everything you need is off-repository, so the documentation site and the commercial course are part of the product rather than an appendix to it. Two practical checks. Which package you actually install, because the repository's root package is private and named differently from the published one, and its version field is five patches behind the newest tag. And where the version number lives, because three tools write it and only one of them is the source of truth. The default branch is not called main, and it was last pushed on 2026-10-02.

Frequently asked questions

Official sources

1. codigoencasa/builderbot on GitHub
2. License: MIT
3. Project website
4. README
5. Releases