# Installation

> Requirements for Wheems, installing the wheems command with npm, and checking the machine with wheems doctor.

By the end of this page the `wheems` command is on your Mac and `wheems doctor` confirms that Node.js and Herdr core are ready. Setting up Slack and your first workspace comes next, in the [Quick start](https://wheems.dev/docs/quick-start/).

## Requirements

| You need | Version | Why |
| --- | --- | --- |
| **macOS** | Any recent version | The service runs under launchd. Linux is planned (see below). |
| **Node.js** | 22.16 or later in the 22 line, or 24 or later (not 23) | Wheems is a Node.js program. Search needs the full-text search in Node's built-in SQLite, which Node bundles from 22.16 and 24.0. |
| **Herdr core** (`hc`) | 0.1.20 or later | Runs every agent in a terminal that stays alive. Wheems refuses to run on an older `hc`. |
| **git** | Any | Your install folder is a git folder, so every version of every page is kept. |
| **An engine** | Claude Code, Codex or opencode | The agent CLI your chief of staff runs in. `wheems setup` installs it for you. |
| **A Slack workspace** | Free plan is fine | Where you talk to your agents. You need to be able to add apps. |

And an account for the engine you choose: a Claude subscription for Claude Code, a ChatGPT subscription for Codex, or an OpenRouter or provider key for opencode (it also has free models). See [Engines and accounts](https://wheems.dev/docs/engines/).

> **Planned · milestone 10:** Wheems runs on a Mac today, and agents answer only while it's awake. Running on an always-on Linux server, with laptops connecting to it, is planned for milestone 10.

## Install

1. **Check Node.js.**

   ```bash title="Terminal"
   node --version
   ```

   ```text title="Output"
   v22.23.4
   ```

   Node 22.16 or later in the 22 line works, as does Node 24 or later. **Node 23 doesn't**: no Node 23 release has SQLite's full-text search, which Wheems's search needs. Homebrew's plain `node` may be 23, so if yours is 23 or older than 22.16, install Node 22 or 24:

   ```bash title="Terminal"
   brew install node@22
   ```

   Or download Node 24 from [nodejs.org](https://nodejs.org). Builds of Node that use the system's own SQLite can lack full-text search whatever their version; `wheems doctor` checks for it (step 5).

2. **Check Herdr core.**

   ```bash title="Terminal"
   hc --version
   ```

   ```text title="Output"
   hc 0.1.20
   ```

   If `hc` isn't found, install Herdr core by following the instructions at [herdr.dev/core](https://herdr.dev/core/). If it's older than 0.1.20, update it. This restarts an older core and keeps your terminals running:

   ```bash title="Terminal"
   hc update
   ```

   > **Planned · milestone 10:** `wheems setup` will install the right Herdr core version for you. Until then, install it yourself from [herdr.dev/core](https://herdr.dev/core/).

3. **Install the `wheems` command.**

   ```bash title="Terminal"
   npm install -g wheems
   ```

   On an unsupported Node.js, npm warns, and `wheems` refuses to start, naming the versions that work. To build from source instead, see [Installing from source](#installing-from-source).

4. **Check it runs.**

   ```bash title="Terminal"
   wheems --version
   ```

   ```text title="Output"
   0.0.3
   ```

5. **Run doctor.**

   ```bash title="Terminal"
   wheems doctor
   ```

   On a new machine, with no install yet, it checks Node.js, its SQLite and Herdr core, and skips the rest:

   ```text title="Output"
   System
     ✓ Node.js: 22.23.4 is supported
     ✓ SQLite search: Node's SQLite has full-text search
     ✓ platform: macOS

   Herdr core
     ✓ hc installed: hc 0.1.20
     ✓ hc version: 0.1.20 meets the minimum 0.1.20
     ✓ Herdr core: Core 0.1.20 is running
     ✓ round trip: Started, sent to, waited on and read a test session

   Config
     - install: No install at /Users/you/wheems yet
         wheems setup creates one. Set WHEEMS_HOME or --home to check another folder.

   Doctor passed.
   ```

   The install is created in the next step, by `wheems setup`. The round trip starts a tiny test session in Herdr core and removes it again; `wheems doctor --quick` skips it.

## If your default Node.js isn't supported

Wheems runs on the Node.js that runs the `wheems` command. On an unsupported one it stops straight away and says why:

```text title="Output"
Node.js 23.11.0 can't run Wheems: no Node 23 release has SQLite full-text search, which Wheems's search needs. Use Node.js 22.16 or later in the 22 line, or 24 or later.
This is /opt/homebrew/Cellar/node/23.11.0/bin/node.
```

If you can't change your default `node`, run Wheems with a supported one directly:

```bash title="Terminal"
/opt/homebrew/opt/node@22/bin/node "$(npm root -g)/wheems/dist/cli/main.js" doctor
```

The service remembers the Node.js you installed it with, so run `wheems service install` with the supported one too. `wheems doctor` says which Node.js it's running on. It fails when the version isn't supported, and also when that Node's SQLite has no full-text search (the **SQLite search** check), which can happen with builds that use the system's SQLite.

## Installing from source

To run the latest code, or to work on Wheems:

```bash title="Terminal"
git clone https://github.com/wheems-dev/wheems.git ~/Projects/wheems
cd ~/Projects/wheems
npm install
npm run build
npm link
```

`npm link` puts the `wheems` command on your `PATH`, pointing at this copy. Clone it anywhere except `~/wheems`: that folder is your install, with your private config and knowledge base. After pulling changes, run `npm run build` again.

## Where things go

Installing puts only the `wheems` command on your Mac. `wheems setup` creates the rest:

| Path | What it is |
| --- | --- |
| `~/wheems/` | Your install: config, the page about you, skills and workspaces. A git folder that's never pushed anywhere. |
| `~/wheems/.wheems/` | Running state: conversations, logs, search indexes. Never committed. |
| `~/.config/wheems/secrets.json` | Your Slack tokens, readable only by you. |
| `~/Library/LaunchAgents/dev.wheems.service.plist` | The service, once you install it. |

Set `WHEEMS_HOME`, or pass `--home <dir>`, to use another install folder.

## Updating

From npm:

```bash title="Terminal"
npm install -g wheems@latest
wheems service restart
```

From source, in your copy of the repository:

```bash title="Terminal"
cd ~/Projects/wheems
git pull
npm install
npm run build
wheems service restart
```

While Wheems is 0.0.x, any release may change config formats or where files live. Read the [changelog](https://github.com/wheems-dev/wheems/blob/main/CHANGELOG.md) first, then run `wheems doctor`.

## Uninstalling

```bash title="Terminal"
wheems service uninstall
npm uninstall -g wheems
```

This leaves your install folder, `~/wheems`, and your tokens in `~/.config/wheems/`. Delete them yourself if you want them gone, and remove the Slack app from **api.slack.com/apps**.

## Next

Continue with the [Quick start](https://wheems.dev/docs/quick-start/).