Installation

#Before you start

You need three things:

• A Branchmore account. Create an account if you don't have one yet.
• A supported system. macOS, Linux, or Windows through WSL, with Claude Code, Codex, or Cursor. Supported platforms has the details.
• Your agents on the same machine. bmor init looks for each agent's config folder (~/.claude, ~/.codex, ~/.cursor) and sets up only the agents it finds. If you add an agent later, run bmor init setup-hooks and bmor init setup-skills.

#Basic setup flow

The sections below explain each step in more detail. On Windows, run every step inside WSL.

1. Install bmor. If the script prints a line to add to your shell profile, add it, then open a new terminal.
   TerminalCopy

   $ curl -fsSL https://raw.githubusercontent.com/branchmore/cli/main/install.sh | sh

2. Set it up. Press Enter at each prompt to keep the defaults, and log in when your browser opens. For a new account, that means Full Mode, which uploads your transcripts. Set up with bmor init explains each prompt, including Stats Mode. If you use Codex, open it afterward, run /hooks, and approve the Branchmore hooks.
   TerminalCopy

   $ bmor init

3. Upload your history. This sends the sessions you had before you installed bmor, so your dashboards have data on day one.
   TerminalCopy

   $ bmor sync backfill

From then on, bmor picks up every new session on its own.

#Installation options

The basic setup flow uses the install script, but you can pick any method below. They all install the same bmor binary.

#Install script

For macOS and Linux. The script installs the latest release to ~/.local/bin without sudo, and prints the line to add to your shell profile if that folder isn't on your PATH. If it can't write there, it falls back to /usr/local/bin with sudo.

$ curl -fsSL https://raw.githubusercontent.com/branchmore/cli/main/install.sh | sh

#Homebrew

For macOS and Linux. bmor is a cask in our own tap, so if you use a Brewfile, list both tap "Branchmore/homebrew-tap" and cask "bmor".

$ brew tap Branchmore/homebrew-tap
$ brew install bmor

On macOS, the first run after a Homebrew install can show a prompt titled "bmor" Not Opened, because our binaries aren't notarized by Apple yet. To allow it, open System Settings, go to Privacy & Security, scroll down to Security, and click Open Anyway next to the message about bmor. The button is only there for about an hour after the blocked run. Then run bmor again.

#npm

For macOS and Linux. It needs Node.js 14 or later and installs the right binary for your platform.

$ npm install -g @branchmore/cli

#Windows

On Windows, bmor runs inside WSL. Install it in the same WSL distro as your agents, with any method above, and it works the same as on Linux. Supported platforms has the details.

Running bmor directly on Windows isn't supported. If you'd like it to be, let us know.

#Initialize

#Set up with bmor init

$ bmor init

Init walks through five steps, in this order:

1. Settings file. It creates ~/.branchmore and writes settings.example.toml there, listing every setting you can change. The settings file explains how to change one.
2. Skills. It adds a /bmor skill to Claude Code and a $bmor skill to Codex, which you can use to mark points in a conversation. If you already have your own skill named bmor, it's left alone.
3. Hooks. It lists the agents it found and asks Set up hooks for detected providers? [Y/n]. Press Enter to register bmor's session start and end hooks with each one. What runs on your machine lists exactly what it adds. If you answer n, init prints the entries to add by hand, and you can run bmor init setup-hooks later. Codex needs one more step: init turns on hooks in ~/.codex/config.toml, but Codex won't run them until you approve them. Open Codex, run /hooks, and approve the Branchmore hooks.
4. Login. It opens a browser on this machine to log you in. Over SSH, in a container, or anywhere without a browser, run bmor init --headless instead. It prints a URL to open on any device, then asks you to paste back the code that page shows.
5. Full Mode or Stats Mode. It asks Which mode? [full/stats]. Full Mode uploads your transcripts and powers every feature. Stats Mode uploads numbers and structure, with no transcript content. Press Enter to keep your account's current mode, which is Full Mode for a new account. What Branchmore collects shows the same session in each mode, and Stats Mode explains what you give up. You can switch at any time.

From then on, each time a session starts, bmor shows a notice in your agent that starts "This session is being monitored by Branchmore". If the session's folder is excluded in your settings, the notice says it's not being monitored. For Claude Code, that session's status-line data is still uploaded. To turn the notice off, see Session start notice.

#Upload your history

Hooks pick up every session from now on. To upload the sessions you had before you installed bmor, so your dashboards have real data on day one, run:

$ bmor sync backfill

It covers every agent, or just one with --provider claude, codex, or cursor. It follows your current mode and skips transcripts from excluded projects. Some agents delete old local logs over time (Claude Code does after 30 days by default), so backfill can only send what's still on disk.

#Maintenance

#Check your setup

To confirm everything is connected, run:

$ bmor config doctor

It checks your settings, that bmor can reach Branchmore, each agent's hooks and skills, Codex's hook setting and approval, and your login. Anything that needs fixing comes with a hint. To see which account you're logged in as, run bmor auth status.

#Check your logs

bmor keeps a log of what it does, including the uploads your hooks start in the background. To see its last 50 lines, run:

$ bmor config logs

Add -n 200 to see more. If sessions aren't showing up in Branchmore, look for lines that start with [warn] or [error]. The log records file and folder paths, counts, and errors, not your conversations. The folder paths show which projects you work in, so look it over before you share it.

For more detail, add --log-level debug to any command. For example, to upload any sessions still waiting and log each step, then read the result:

$ bmor sync --log-level debug
$ bmor config logs

Hooks run with your agent's environment, so to get debug logs from them, set LOG_LEVEL=debug in the shell you start your agent from.

The log is ~/.branchmore/bmor.log. Once it passes 5 MB, bmor renames it to bmor.log.1, replacing the previous one, and starts a new log. bmor config logs only reads the current file, so open bmor.log.1 directly for older entries.

#Update

How bmor updates depends on how you installed it:

• Install script or manual download: bmor updates itself. Whenever it runs, including the background upload at the start of each session, it checks for a new release at most once a day and installs it. To update right away, run bmor update. To only check, run bmor update --check.
• Homebrew: run brew upgrade bmor. On Linux, Homebrew keeps each version in its own folder, so your hooks can still point at the old one afterward. Run bmor config doctor, and if it reports conflicting bmor entries, reinstall the hooks.
• npm: run npm install -g @branchmore/cli.

If the install script put bmor in /usr/local/bin with sudo, bmor can't replace itself there, so automatic updates quietly fail. Run sudo bmor update instead.

To turn off automatic updates, see Automatic updates.

If sessions stop showing up after an update, run bmor config doctor.

#Verify releases

Every release is built in CI and published on GitHub Releases with a SHA-256 checksum file, checksums.txt.

• The install script checks the download against that file and stops if they don't match. It needs sha256sum or shasum to do this. If neither is installed, it warns you and skips the check. It also skips the check, without a warning, if the download isn't listed in the checksum file.
• The built-in updater always checks, and refuses an update that doesn't match.
• The Homebrew cask pins the SHA-256 of each platform's download.
• npm packages are published with provenance, which ties each package to the GitHub Actions workflow that published it.

A checksum that comes from the same release catches a corrupted download, not a tampered release. Releases aren't cryptographically signed, and the CLI's source isn't public yet.

#Troubleshooting

#Missing Cursor conversations

Some Cursor editor conversations are kept only in the editor's database, not in its transcript folders. Make sure bmor knows where that database is before you upload your history, so those conversations come along too. CLI Configuration shows the setting. If you've already uploaded your history, run bmor sync backfill again after you set it.

#Hooks pointing at an old copy of bmor

Each hook records the full path of the bmor that installed it. If that path changes, for example because you switched install methods, moved the binary, or upgraded with Homebrew on Linux, init won't overwrite the old entries. Init prints hooks not updated; conflicting bmor entries remain, and bmor config doctor reports conflicting bmor entries. If you switched methods, remove the old install first so only one bmor is on your PATH (for example, brew uninstall bmor, npm uninstall -g @branchmore/cli, or rm ~/.local/bin/bmor). Then reinstall the hooks:

$ bmor init setup-hooks --remove
$ bmor init setup-hooks

If you use Codex, approve the hooks again with /hooks.

#Uninstall

To uninstall, run:

$ bmor uninstall

bmor uninstall automatically logs you out as part of uninstalling.

bmor uninstall lists what it will remove and asks you to confirm. It removes:

• bmor's hooks from Claude Code, Codex, and Cursor, including bmor's Claude Code status line.
• The /bmor and $bmor skills it added. A bmor skill you made yourself is left alone.
• ~/.branchmore, with your settings, login, logs, and any uploads still waiting to go out.
• The bmor binary, if you used the install script or a manual download. If you installed with Homebrew or npm, it prints the command that finishes the job: brew uninstall bmor or npm uninstall -g @branchmore/cli.

If bmor can't delete its own binary, it tells you. After a sudo install in /usr/local/bin, remove it with sudo rm /usr/local/bin/bmor.

Uninstall leaves these behind:

• Codex settings. The [features] hooks = true line in ~/.codex/config.toml, and the hook approvals Codex saved there. Remove them by hand if nothing else uses Codex hooks.
• Data you've already uploaded. Uninstalling doesn't delete it. Retention and deletion explains how long we keep it and how to have it deleted.