Installation | Wheems docs

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.

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.

Install

Check Node.js.
Terminal
```
node --version
```
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:
Terminal
```
brew install node@22
```
Or download Node 24 from 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).
Check Herdr core.
Terminal
```
hc --version
```
Output
```
hc 0.1.20
```
If hc isn’t found, install Herdr core by following the instructions at herdr.dev/core. If it’s older than 0.1.20, update it. This restarts an older core and keeps your terminals running:
Terminal
```
hc update
```
wheems setup will install the right Herdr core version for you. Until then, install it yourself from herdr.dev/core.
Install the wheems command.
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.
Check it runs.
Terminal
```
wheems --version
```
Output
```
0.0.3
```

Run doctor.

wheems doctor

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

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:

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:

/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:

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:

npm install -g wheems@latest
wheems service restart

From source, in your copy of the repository:

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 first, then run wheems doctor.

Uninstalling

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.

Continue with the Quick start.