BRAT, the plugin that updates your other Obsidian plugins

The problem it removes

BRAT stands for Beta Reviewers Auto-update Tool, and it is described as a very special plugin designed to make life much easier for developers and beta-testers of plugins and themes.

The workflow it replaces is the point. The README describes the manual loop in a single sentence: you had to create folders, download files, copy them to the right place, and so on. That is the procedure every Obsidian plugin author asks their beta testers to follow, and it is a procedure that fails in predictable ways. A tester downloads a zip, extracts it into a plugin folder with the right name, restarts Obsidian, and if the author has pushed a new commit in the meantime the tester is now on a stale build and does not know it.

BRAT reduces it to adding the GitHub repository path for the beta plugin to a list, and then checking for updates. Updates are downloaded and the plugin is reloaded. The README is explicit that no more having to create folders, download files, copy them to the right place, and so on.

Two consequences follow from that design. The first is that the update cycle for the tester becomes a button rather than a ritual, which means a reviewer actually stays on the current commit. The second is that the tester needs to trust the plugin author, because BRAT is installing and running code that the Obsidian community has not vetted, from a repository the tester names.

The documentation is at tfthacker.com/BRAT, and the author also points to a Twitter account for updates. The homepage of the project is tfthacker.com/BRAT, the licence is MIT, the default branch is main, and the release tags are 2.3.0-beta.1 from 2026-09-22, 2.2.0 from 2026-07-01 and 2.2.0-beta.1 from 2026-06-28, with the last push on 2026-10-17.

What the repository holds, and the beta naming convention

The repository layout shows a plugin project with the extra machinery a released plugin needs.

There is a src/ directory for the TypeScript source, styles.css for the styling, a manifest.json for the Obsidian plugin manifest, a versions.json for the version to manifest mapping that Obsidian plugins use, and an esbuild.config.mjs as the bundler configuration. There is a .husky-style setup through a .githooks/ directory and a .releaserc.yaml for the release configuration.

Two documentation files stand out, and both are for developers rather than users. BRAT-DEVELOPER-GUIDE.md and DEV_NOTES.MD sit at the repository root, and the existence of a developer guide inside a plugin that exists to help other plugin developers is a reasonable guess about who the audience is. The main README is short and points at the external documentation site for everything else, which is the pattern of a project whose users need a guide rather than a summary.

The release names are worth noticing. There is 2.2.0, and there are 2.2.0-beta.1 and 2.3.0-beta.1, and the beta suffix appears on versions that are also the current development line. That is the semantic-release convention, and the package.json shows the tooling: semantic-release with the commit analyzer, the GitHub plugin, the release notes generator, and a semantic-release-obsidian-plugin fork from brianrodri, which is what handles the Obsidian-specific bits of tagging and publishing to the community plugin repository.

The package itself is named obsidian42-brat with a version of 0.0.0, and the version field is managed by the release tooling rather than written by hand, which is why it sits at 0.0.0 while the releases are numbered 2.x. The main entry point is main.js, and the build scripts are named after their target, with build:main and build:dev and build:beta, all going through the esbuild config with a mode argument.

The manifest and the versions file are also how Obsidian plugins are updated in place rather than reinstalled, and a tool whose whole job is updating plugins has to be careful about that mechanism.

Who it is for, and what the author also makes

The README is short, but the audience is stated in the first paragraph. BRAT is a plugin that makes it easier for you to assist other developers with reviewing and testing their plugins and themes, and the summary calls it a very special plugin designed for developers and beta-testers of plugins and themes.

That is a narrow purpose and a useful one. The Obsidian plugin ecosystem has a persistent problem, which is that a plugin under active development is not in the community plugin directory yet, so testers install it by hand, and the author has no way to push a fix to them. BRAT is the missing half of the release process for those plugins. It is a testing tool that happens to be a plugin, and reading it that way explains the small runtime dependency, the careful build setup and the separate developer guide.

It also explains why the project is written by someone who makes other Obsidian products. The README points at two of them. JournalCraft is a curated collection of 10 journaling templates for enhancing your journaling experience, and the Cornell Notes Learning Vault teaches the Cornell Note-Taking System in an Obsidian vault, including learning material, samples and Obsidian configuration files to enable Cornell Notes.

Both are products for the same audience, the person who uses Obsidian as a notes system rather than as a developer, and the fact that the author builds for both sides is a reasonable signal about how the plugin ecosystem around Obsidian actually works. A tool for developers who write plugins, and a set of templates for the people who use them.

The practical detail for anyone evaluating the plugin is the trust question again. BRAT pulls a plugin from a repository you name and loads it into your editor, and the plugin you are testing is by definition unreleased and unvetted. That is the deal, and it is a reasonable one between a plugin author and a volunteer tester, but it is not a deal you would make with a repository you found by accident.

The toolchain, and the one runtime dependency

The dependency list is short in a way that matters for a plugin, because Obsidian plugins run in the user's application and every dependency is code you are asking users to execute.

There is exactly one runtime dependency, semver at 7.7.2, which is what lets BRAT compare the installed beta version against the latest tag in a repository. Everything else is a development dependency.

The build stack is esbuild 0.28.1 with an esbuild-copy-static-files plugin, and the scripts are explicit about the two build modes, production for the main build and a beta mode used by the beta build script. The linting is doubled up, with biome check over the src directory and eslint over the project, and there is a biome.json and an eslint.config.mts at the root along with an eslint-plugin-obsidianmd for the Obsidian specific lint rules. The type tooling is TypeScript 5.9.2 with typescript-eslint, typedoc for API documentation, and the Obsidian public type definitions pinned at 4.93.0 for the 1.11.4 API surface.

Two details are worth pulling out. The overrides field pins obsidian to 1.11.4, matching the devDependency, which is a way of making sure the type definitions and the runtime the plugin is tested against do not drift apart. And the dependencies on jsdom and jiti suggest the test setup runs some of the plugin logic outside Obsidian, in a DOM environment, which is a sensible approach for a plugin that otherwise can only be exercised by launching the whole editor.

The scripts themselves are short enough to be worth reading as a summary of the workflow. dev runs the dev build, build runs the main build, lint runs both linters, and the release process is not a script here but a semantic-release configuration in the repository.

The result is a plugin that is small in what it ships and careful in how it is built, which is the right balance for something whose purpose is to run other people's unreleased code inside your editor.

Editorial conclusion

BRAT suits a plugin or theme author who needs reviewers to be testing the current commit rather than a published release, because it turns a manual install ritual into a check-for-updates click. It is the wrong choice if you only want stable plugins, since the whole point is beta builds, and it is the wrong choice if you do not trust the plugin you are pulling, because BRAT fetches and installs code from a repository you name and runs it inside Obsidian. Before adding a repository, check whether it is one you control, and read the developer guide in the repository, since BRAT-DEVELOPER-GUIDE.md and DEV_NOTES.MD are where the conventions for the update flow are written down.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. TfTHacker/obsidian42-brat on GitHub