Skip to main content
Birdbrain is an open source web investigation and capture tool. The Chrome extension captures a page when you ask it to. The desktop app organizes those captures into cases you can annotate, search, and export, with hashes, timestamps, and audit manifests attached. This is beta software. Expect rough edges, and export anything you can’t afford to lose (see Known limitations). Download Birdbrain has the platform table, where security advisories appear, and what the project wants reported.

​
Your data and your archives

Use synthetic or low-stakes material where you can. Real project data is tolerated, not endorsed. It goes in at your own risk, and Updating describes what backs that risk and where the limits are.
  • Birdbrain does not encrypt the database or capture files at rest. Confidentiality of the live store relies on your operating system’s full-disk encryption (BitLocker, LUKS).
  • The project has no channel for sending a .birdbrain case archive to the maintainer, and a bug report never needs one. See Reporting a problem for what a diagnostic bundle does and doesn’t contain.

​
Install the app

Releases live at github.com/thebristolsound/birdbrain/releases, the public repository that also holds the source code. You need no GitHub account to download a build. Take the current release and the file for your platform; Download Birdbrain says which file that is. Once it’s installed, Settings → About shows the version you’re running.

​
Windows

  1. Download Birdbrain-Setup-<version>.exe and run it.
  2. Windows SmartScreen will warn about an unrecognized app (our builds aren’t code-signed yet). Click More info → Run anyway.
  3. The installer finishes and launches Birdbrain.

​
Ubuntu

The AppImage is the primary Linux build. It needs no install step, and updates replace it in place:
AppImages need FUSE 2, and Ubuntu stopped installing it by default. Without it the app does not start, and the error reads like a broken download rather than a missing library. On 22.04 and earlier the package is called libfuse2 instead of libfuse2t64; if apt cannot find one, use the other. If you would rather not install anything, this runs the same build without FUSE:
The alternative is the .deb:
Then launch Birdbrain from your app launcher, or run birdbrain in a terminal. The .deb gets best-effort support, and installing an update on it needs your system password. See Updating.

​
macOS

macOS support is experimental, and needs macOS 13 or later. The build is unsigned, not notarized, and not launch-tested before it is published. A release whose macOS build fails still ships, without it.
  1. Download Birdbrain-<version>-arm64.dmg on Apple Silicon, or Birdbrain-<version>.dmg on an Intel Mac. If the release lists neither file, it has no macOS build.
  2. Open the disk image and drag Birdbrain to Applications.
  3. The build is not signed or notarized, so macOS blocks the first launch, and may say the app is “damaged and can’t be opened”. That message is the download quarantine, not a corrupt file. Clear the quarantine once in Terminal, then open Birdbrain as usual:
The app does not install updates on macOS. To update, download the new disk image from the releases page and repeat the steps.

​
Install the Chrome extension

The extension isn’t on the Chrome Web Store yet, so it loads in developer mode. The extension card on the Birdbrain dashboard has a Setup Guide that walks through the steps and an Open extension folder button that opens the right folder for you. If a case is open, click the house icon (Home) at the top of the left sidebar to reach the dashboard. The short version:
  1. Open chrome://extensions in Chrome.
  2. Switch on Developer mode (toggle in the top-right corner).
  3. On the Birdbrain dashboard, click Open extension folder. This opens the copy of the extension that belongs to the Birdbrain build you just installed. Always load this one, not a copy downloaded or unzipped from somewhere else, so the extension and the desktop app stay the same version.
  4. Click Load unpacked and select that folder, the one containing manifest.json.
  5. The Birdbrain icon appears in your Chrome toolbar. Back in the app, a green Connected badge appears in the top bar.
Chrome keeps running the copy it loaded until you reload it, so an app update needs one more step from you (see Updating). The desktop app must be running for the extension to work. The extension sends captures only to the app, over 127.0.0.1:19845. The app itself contacts outside services. For example, it sends each capture’s hash to a timestamp authority unless you switch off Settings → Operator → Trusted timestamping. The network egress section of the security policy describes them.

​
Your first capture

  1. In the app, go to the dashboard and click Start New Case. Name the case anything.
  2. Browse to any page in Chrome.
  3. Click the Birdbrain toolbar icon, then click Capture now. You can also right-click the page and choose Birdbrain → Capture Full Page.
  4. The capture appears in the app under your case’s Captures tab, with provenance details (hashes, timestamps) attached.
From there, explore: annotate screenshots, add notes and tags, define selectors, search the text of every capture in the case from the search box in the top bar (Ctrl F), and export the case when you’re done.

​
Updating

Settings → Updates → Check automatically is on out of the box, and while it is on Birdbrain checks for updates by itself: shortly after launch, then every few hours while it’s running. Anything it finds downloads by itself too. Because you’re on a prerelease build, it starts on the Beta channel, so new betas count as updates. Switch Check automatically off and no background check runs at all. An update will never surface on its own, and opening the Updates panel won’t go looking for one either. You have to click Settings → Updates → Check for updates yourself, then click Download on whatever it turns up. That button works whatever the toggle says. Nothing ever restarts on its own. A downloaded update installs when you click Restart to update, or quietly at your next quit. The .deb is the exception. Updates download the same way, but installing one runs dpkg behind a system password prompt, so it never installs at quit, only when you click Restart to update and enter your password. That’s why the AppImage is the primary Ubuntu build, and why on the .deb it is worth watching the releases page. macOS is the other exception. Nothing downloads or installs by itself, and there is no Download button. Update by hand as described in macOS. You can always install by hand instead: download from the releases page and install over the old version. Your data survives either way. It lives in your user data directory, separate from the app. After every app update, also reload the extension: chrome://extensions → click the reload icon on the Birdbrain card. Chrome does not pick up changed extension files on its own, so until you reload, the extension is still the previous version, and captures it makes may not match what the app expects. The folder Open extension folder opens is a copy the app keeps in its user data directory and refreshes whenever the app version changes. The path stays the same across updates, so a card you loaded from it keeps working after a reload. If you installed Birdbrain before that folder moved, though, your card still points at the old app install folder. The dashboard shows Open extension folder only while no extension is connected, so if the old card still connects, the button is not there. Open the folder yourself instead. It is the extension folder in Birdbrain’s user data directory. To find that directory, go to Settings → Diagnostics → Log and click Reveal log file. Your file manager shows the log file inside a logs folder. Go up one level, and the extension folder is beside logs. Load unpacked that extension folder, then remove the older Birdbrain entry pointing somewhere else. Leave both loaded and Chrome runs the stale one. If you put real project data in, this is what stands behind it, and the limits below are why we recommend synthetic or low-stakes material instead. When a new version needs to upgrade the case database, Birdbrain copies the database first, into a db-snapshots folder next to it in your user data directory, and only then applies the upgrade. If the copy fails, the upgrade does not run at all. You get an error saying so, and your data stays exactly as it was. Birdbrain keeps three snapshots, spread across the schema versions present rather than newest-first, so a run of failed upgrades does not immediately fill the folder with copies of the same half-migrated state. It prunes older ones, so copy any snapshot you want to keep out of that folder. You can put one back from Settings → Database → Utilities → Pre-Migration Snapshots. Restoring a snapshot cannot be undone. The copy overwrites your current database, and Birdbrain does not keep the old one anywhere. Birdbrain provides no undo button and no aside file to rename back. If you might want the current state again, take a copy first with Settings → Database → Utilities → Backup Database, which writes the database wherever you choose, and export anything recorded since the snapshot that matters. Export is the only backup that includes capture files; Backup Database copies the database alone. A failed restore is not a guarantee either. If the restore fails, treat the result as unknown. A restore error does not prove the previous database is still intact, and case data can end up inconsistent. Check the case before carrying on, or restore a backup. The exception is a refusal whose message ends “Nothing was changed.”, such as Restore from File turning down a file that is not a Birdbrain database: Birdbrain stopped before replacing anything, and your database stays as it was. Two more things a restore does not do, both worth knowing before you click it:
  • It does not take you back to the old schema. Birdbrain re-opens the restored copy and applies the same upgrade to it again, so you end up on the current schema holding the older records. That is what you want when an upgrade died half-way through, but it is not a downgrade.
  • It only replaces the database. Capture files, screenshots and MHTML stay on disk. Anything recorded after the snapshot disappears from the app while its files remain, unreferenced.

​
Known limitations

  • Unsigned builds. SmartScreen warnings on Windows are expected.
  • Updates never restart the app for you. Installing is your click, or your next quit on Windows and the AppImage. The .deb never installs at quit; it’s always your click plus your system password.
  • The extension is sideloaded. Chrome may occasionally nag about developer-mode extensions.
  • One running copy at a time. The extension reaches the app on 127.0.0.1:19845, and only one program can hold that port. Launching Birdbrain while it is already running brings the copy you have to the front instead of starting a second one, so you can’t collide with yourself. If some other program on your machine is holding that port, Birdbrain refuses to start rather than open a window that can’t receive captures, and names the port in the error it shows. Close whatever is using it, then start Birdbrain again.
  • Local-only data. Captures live only on your machine, and export is the only backup that includes capture files. Export anything you can’t lose before updating or uninstalling.
  • Deleting a capture is not redacting it. The files go, but the case manifest is append-only: the deleted capture’s URL, capture time and hashes stay in it permanently and ship in every export that includes the audit trail. If a URL is sensitive, deleting the capture does not take it out of the evidence package. Treat a case as contaminated by anything you captured into it.
  • Chrome/Chromium only. No Firefox or Safari extension yet.
  • macOS is experimental. The build is unsigned and not notarized, and the app does not install updates on macOS.
  • “Verified” is not a live check. Capture details shows the result of the last verification run, not the state of the file right now. Click Re-verify to get a current statement.

​
Reporting a problem

Report what you find as an issue on the Birdbrain repository. It is public, and no response target is stated. If you find a security vulnerability, do not open a public issue. Report it privately through the repository’s Security tab, as its security policy describes. Birdbrain keeps a local diagnostic log and can bundle it into a report for you:
  1. Go to Settings → Diagnostics → Report a problem.
  2. Fill in what you did, what you expected, and what happened.
  3. Click Create report. Pick where to save it. Birdbrain writes a .zip there and opens the folder for you.
The zip saves only to your computer. Birdbrain never uploads it or sends it anywhere. Attach it to the issue yourself, the same way you’d attach any other file. It contains:
  • the diagnostic log, plus the previous log file if the log has rotated
  • what you typed in the report form, the time you made the report, and, if you opened it with Report this on an error message, that error’s log entry ID
  • your installation identifier
  • a record of your last 20 app launches: a random ID for each, when it started and ended, whether it closed cleanly, whether its crash prompt was shown, and the version, platform and install format it ran
  • a snapshot of the app’s state: the Birdbrain, Electron, Chrome and Node versions, your operating system, processor type and install format, how long the app has been running, each app process’s type, ID, CPU and memory use, how far the app is lagging now and at worst in the last minute, recent freezes and named slow operations with their times and durations, your database’s schema version and the newest one this build supports, how many cases, captures, notes, selectors and extracted data items you have, the size of your case database files, whether your signing key is stored encrypted, and whether trusted timestamping is on
It does not contain your captures, your case database, or your settings file. That is why no bug report needs a case archive, and there is no channel for sending one. Birdbrain writes the same installation identifier into the manifest entry of every capture you take, so attaching the bundle to a public issue links that issue to the evidence packages you export. If Birdbrain closed unexpectedly last time (a crash, a forced quit, a power loss), it will offer to create a report automatically the next time you open it. Click Create a report on that prompt to file it the same way. You can also open Settings → Diagnostics → Log any time to see recent log entries in the app itself, filterable by level, with a button to reveal the raw log file on disk.

​
What to put in the issue

  1. Version. The build you’re running. Settings → About shows it, Settings → Diagnostics repeats it, and it’s in the installer filename too.
  2. OS. For example Windows 11 or Ubuntu 24.04.
  3. What you did. Steps, in order.
  4. What you expected.
  5. What happened. Plus a screenshot if it’s visual.
Attach a diagnostic bundle alongside your description. Good repro steps plus a report bundle is the single most useful thing you can give us. Small, frequent reports beat one big write-up.