Quick start | Wheems docs

By the end of this page you’ll have an install folder, a workspace called personal with its chief of staff, the Wheems service running in the background, and a first answer in Slack. It takes about fifteen minutes, most of it in Slack’s app settings.

Before you start

Wheems is installed and wheems doctor passes System and Herdr core. See Installation.
You have a Slack workspace where you can add apps.
You have a Claude subscription (for Claude Code), a ChatGPT subscription (for Codex), or an OpenRouter or provider key for opencode.

Set up

Everything below happens in one command. It offers a menu, and suggests the next section each time you finish one.

wheems setup

◇  Created your install at /Users/you/wheems
│
◆  What do you want to set up?
│  ● Engines (install Claude Code, Codex or opencode for your agents)
│  ○ Channels
│  ○ Workspaces
│  ○ Knowledge
│  ○ Service
│  ○ Check everything
│  ○ Done

Pick with the arrow keys and Enter. Esc or Ctrl+C backs out of a step without saving it. You can run wheems setup again any time; it picks up where you are.

The first time, setup creates ~/wheems: an install.yaml, an about-you.md page, a .gitignore, and git init.

Engines: install and sign in to an engine.

Choose Engines. Setup looks for Claude Code, Codex and opencode, and shows each one’s version and whether it’s signed in. Pick one. If it isn’t installed, setup shows the install command and asks before running it:

◆  Install Claude Code with: npm install -g @anthropic-ai/claude-code?

Then it runs the engine’s own sign-in on your terminal, so you log in yourself:

Engine	Installs with	Signs in with
Claude Code	`npm install -g @anthropic-ai/claude-code`	`claude auth login`
Codex	`npm install -g @openai/codex`	`codex login`
opencode	`npm install -g opencode-ai`	`opencode providers login` (optional: its free models need none)

One engine is enough to start. Claude Code is the default.

Channels: connect Slack.

Choose Channels, then Slack. Setup walks you through creating the Slack app from a manifest, pasting its two tokens, and giving your Slack member ID. Every step, and what to click in Slack, is in Connecting Slack.

When it’s done:
Output
```
◆  Slack is connected. Its tokens are saved privately in /Users/you/.config/wheems/secrets.json
```
Workspaces: create your first workspace.

Choose Workspaces and answer:
- Workspace id: personal. Lowercase letters, digits and dashes. It becomes the folder name.
- Its name: Personal.
- Where will you chat with it?: The app’s direct messages. Only the first workspace gets them; later ones chat in a channel.
- Which engine runs its chief of staff? and Model: the default is Claude Code with claude-opus-5-5.
Output
```
◆  Created /Users/you/wheems/workspaces/personal, with its chief of staff on Claude Code (claude-opus-5-5)
```
Trust the workspace folder.

Claude Code and Codex ask once whether to trust a new folder, and nobody can answer that from Slack. Setup offers to open the engine in the workspace folder:
Output
```
◆  Open Claude Code there now?
```
Say yes, answer the engine’s trust question with yes, then press Ctrl+C twice to come back to setup. If you skip it, the first message waits for that answer at the Mac. opencode doesn’t ask.
Knowledge: choose how agents search (optional).

Choose Knowledge. Keyword search only needs nothing installed. By meaning, with Ollama also finds pages that use different words, with a free model on your Mac. You need Ollama running; setup offers to download nomic-embed-text if it’s missing. You can change this later. See Knowledge base and search.
Service: run Wheems in the background.

Choose Service. Setup installs the service under launchd, now and at every login, and waits until it answers:
Output
```
◇  The service is running, now and at every login
```
Check everything.

Choose Check everything, which runs wheems doctor. Every check should pass or be a warning you understand. Then choose Done.

Talk to your chief of staff

In Slack, find Wheems under Apps in the sidebar and open its Messages tab.
Send a message:
Slack
```
Hello! What can you do for me?
```
A 👀 reaction appears within a few seconds: your message has reached the agent. The answer arrives in the message’s thread, and the 👀 goes.
Reply in that thread to carry the conversation on. A new message outside the thread starts a new conversation.

Each conversation is its own engine session in Herdr core. To watch it, or type into it yourself, list the sessions and attach:

hc ls
hc attach t7

Press Ctrl+\ to detach without stopping it.

Tell it about you

Open ~/wheems/about-you.md and write what you’d tell anyone working for you: how you like to work, how you like things written. Every agent in every workspace reads it when it starts. Only the first 4,000 characters are loaded.

# About me

## How I like to work

I run a small design studio. Mornings are for client work; don't book anything before 11.

## How I like things written

British English. Short sentences. Lead with the answer.

Agents never change this page. When they learn something about you, they suggest a change, which you approve with wheems review.

What happens next

Notes. When a conversation has been quiet for 30 minutes, Wheems asks the agent for a note. It lands in workspaces/personal/knowledge/inbox/, and the filer turns it into knowledge base pages. You won’t see this in Slack.
Review. Now and then, run wheems review. It shows skills agents proposed, and changes to about-you.md suggested from their notes. Nothing changes until you approve it.
Reports. Overnight, Wheems writes knowledge/reports/contradictions.md and knowledge/reports/stale.md.

Once wheems setup has created the install and connected Slack, each part has its own command, for scripts:

wheems init acme --channel acme-chat                     # a workspace that chats in #acme-chat
wheems init research --channel research-chat --engine codex
wheems service install
wheems doctor

On a new machine, wheems init creates the install folder first, so this works from a script; connecting Slack still needs wheems setup. After init, it prints the commands to trust the folder:

Created /Users/you/wheems/workspaces/acme, with its chief of staff on Claude Code

Claude Code asks once whether to trust a new folder, and nobody can answer it from Slack.
Answer it now: run the two lines below, say yes, then quit it.

  cd /Users/you/wheems/workspaces/acme
  claude

Then invite the bot to #acme-chat and restart the service: wheems service restart

If something goes wrong

Problem	What to do
No 👀 on your message	Run `wheems doctor`, then see the Slack troubleshooting table.
Wheems: The agent hasn’t started on this yet…	The engine is waiting for an answer at the Mac, usually the folder trust question. Run the `hc attach` command in the notice.
`Workspace personal already chats in the bot's direct messages`	Only one workspace can have direct messages. Give this one `--channel <name>`.
`"Acme" is not a workspace name`	Use lowercase letters, digits and dashes, such as `acme`.
The service isn’t answering	`wheems service logs`. See Running as a service.