How to install WimprFlow on Mac

Before you start

These are one-time installs. If you have used Terminal before, you may have them already — the first step checks.

1. 1

   Install Git

   Apple opens a small installer.

   Type this into Terminal, then press Return.

   Copy the command for step 1

   xcode-select --install

   You know this worked when: Git responds with a version number

2. 2

   Install Node LTS

   Choose the macOS Installer (.pkg).

   Open download ↗

   You know this worked when: Node responds with a version number

Install WimprFlow

1. 3

   Open Terminal

   Keep it open beside this page.

   You know this worked when: Terminal is open

2. 4

   Check Git and Node

   Git and the current Node LTS are required.

   Type this into Terminal, then press Return.

   Copy the command for step 4

   git --version
   node --version

   You know this worked when: Git and Node respond with version numbers

3. 5

   Install Rust

   Run the single command the page shows, then reopen Terminal.

   Open rustup ↗

   You know this worked when: cargo responds with a version number

4. 6

   Install pnpm

   The UI is a pnpm workspace. Installed into a folder you own, so no admin password.

   Type this into Terminal, then press Return.

   Copy the command for step 6

   mkdir -p "$HOME/.npm-global/bin"
   npm install -g --prefix "$HOME/.npm-global" pnpm
   grep -qsxF 'export PATH="$HOME/.npm-global/bin:$PATH"' "$HOME/.zshrc" || echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> "$HOME/.zshrc"
   export PATH="$HOME/.npm-global/bin:$PATH"

   You know this worked when: pnpm responds with a version number

5. 7

   Copy WimprFlow to this Mac

   Type this into Terminal, then press Return. The first line moves you into the folder this step runs in, so it works in a window you have just opened.

   Copy the command for step 7

   cd ~
   if [ ! -d WhimprFlow/.git ]; then
   git clone https://github.com/chrisznb/WhimprFlow.git
   fi

   You know this worked when: A WhimprFlow folder appears

6. 8

   Open the WimprFlow folder

   Type this into Terminal, then press Return. The first line moves you into the folder this step runs in, so it works in a window you have just opened.

   Copy the command for step 8

   cd ~
   cd WhimprFlow

   You know this worked when: Your terminal prompt is inside the WhimprFlow folder

7. 9

   Use the reviewed version

   Type this into Terminal, then press Return. The first line moves you into the folder this step runs in, so it works in a window you have just opened.

   Copy the command for step 9

   cd ~/WhimprFlow
   git checkout 5e99a6c9ce26adb51b167b7e21dd6e5f1f4e7410

   You know this worked when: Git reports the reviewed commit

8. 10

   Install the UI dependencies

   pnpm 10+ holds back dependency build scripts until they are approved; the second line approves them.

   Type this into Terminal, then press Return. The first line moves you into the folder this step runs in, so it works in a window you have just opened.

   Copy the command for step 10

   cd ~/WhimprFlow
   pnpm --dir ui install
   pnpm --dir ui approve-builds --all

   You know this worked when: pnpm finishes without errors

9. 11

   Build WhimprFlow

   Rust and the UI compile together. Several minutes; a warm build is faster.

   Type this into Terminal, then press Return. The first line moves you into the folder this step runs in, so it works in a window you have just opened.

   Copy the command for step 11

   cd ~/WhimprFlow
   ui/node_modules/.bin/tauri build --bundles app

   You know this worked when: A WhimprFlow.app appears under target/release/bundle/macos

10. 12

    Build the language worker

    The on-device text cleanup runs in its own process.

    Type this into Terminal, then press Return. The first line moves you into the folder this step runs in, so it works in a window you have just opened.

    Copy the command for step 12

    cd ~/WhimprFlow
    cargo build --release -p whimpr-llm-worker

    You know this worked when: cargo finishes without errors

11. 13

    Put WhimprFlow in Applications

    The worker rides inside the app bundle.

    Type this into Terminal, then press Return. The first line moves you into the folder this step runs in, so it works in a window you have just opened.

    Copy the command for step 13

    cd ~/WhimprFlow
    cp target/release/whimpr-llm-worker target/release/bundle/macos/WhimprFlow.app/Contents/MacOS/
    ditto target/release/bundle/macos/WhimprFlow.app /Applications/WhimprFlow.app

    You know this worked when: WhimprFlow.app is in your Applications folder

12. 14

    Open WhimprFlow

    Type this into Terminal, then press Return. The first line moves you into the folder this step runs in, so it works in a window you have just opened.

    Copy the command for step 14

    cd ~/WhimprFlow
    open /Applications/WhimprFlow.app

    You know this worked when: WhimprFlow opens

13. 15

    Allow Microphone

    In Privacy & Security, turn on Microphone for WimprFlow.

    You know this worked when: Microphone is turned on

14. 16

    Allow Accessibility

    In Privacy & Security, turn on Accessibility for WimprFlow.

    You know this worked when: Accessibility is turned on

15. 17

    Allow Notifications

    In Privacy & Security, turn on Notifications for WimprFlow.

    You know this worked when: Notifications is turned on

16. 18

    Try it

    WimprFlow should be open and ready to use.

    You know this worked when: WimprFlow works

If something goes wrong

Nothing here can damage your computer, and every step can be run again safely. If a command fails, the usual cause is the step before it not having finished.

Still stuck? Tell us what happened and we will fix the guide. Include the step number and we can usually reproduce it.