# Introduction

> What Wheems is, who it's for, what works in the 0.0.3 early preview, and how these docs are organised.

Wheems is an open-source, opinionated framework for running teams of AI agents. You talk to a **chief of staff** from Slack, and it gets on with the job: in Claude Code, Codex or opencode, on the subscriptions you already pay for, each in a terminal you can watch or take over.

> **Early preview · 0.0.3:** Wheems isn't ready for real use yet. Anything may change between releases, including commands, config formats and where files live, with no migration path. Try it, but don't rely on it. These docs mark everything that isn't built yet as **Planned**, with its milestone.

## A harness first, workflows when you want them

Most agent frameworks start with a workflow: you draw the steps, then agents fill them in. Wheems starts with the harness. You talk to a chief of staff in Slack and it does the work, in an agent CLI, unchanged. Nothing needs a workflow.

When a job repeats, it can be hardened one step at a time: a routine, then a fixed workflow that asks before it acts and graduates to acting alone as its results earn it. Determinism is chosen per step: fixed steps and checks where the job is known, an agent's judgement only where it's needed. Routines and workflows are planned (milestones 5 and 7).

## Who it's for

Wheems is for people who run a business, or several, and want agents doing real work for them: not only code.

- Watching an inbox and acting on each email
- Replying to reviews
- Finding and following up leads
- Bookkeeping
- Growing a website

It suits someone comfortable in a terminal, with a Mac, a Claude or ChatGPT subscription and a Slack workspace.

## How it fits together

![Your message goes from Slack to the Wheems service, which starts a session in Herdr core (hc), where your agent runs in Claude Code, Codex or opencode. The agent talks back to the service with wheems reply, note, kb search and skill propose, and the service posts the answers in Slack.](https://wheems.dev/docs/diagrams/how-it-fits.svg)

- **The install** is a git folder, `~/wheems`, holding your config: install-wide settings, a page about you, the skill library and your workspaces.
- **A workspace** is one business or area of life, with its own chief of staff, agents, chat channel and knowledge base.
- **The service** runs in the background. It holds the Slack connection, starts an agent session for each conversation, posts answers, files notes into the knowledge base and keeps search up to date.
- **The `wheems` command** is what you run to set up and check things, and what agents run to reply, write notes, search and propose skills.
- **Herdr core** (`hc`) runs every agent in a terminal that stays alive. You can attach to any session, watch it work and type into it.

## What works today

Version 0.0.3 is milestones 0 to 2 of the [roadmap](https://wheems.dev/docs/roadmap/).

| Works now | Planned |
| --- | --- |
| A chief of staff per workspace, from Slack, one conversation per thread | Approval buttons and an updates channel (milestone 3) |
| Claude Code, Codex and opencode as engines | Projects with their own lead and channel (milestone 4) |
| Notes, a knowledge base filed for you, and search by keyword and meaning | Tasks between agents, routines and pairs (milestone 5) |
| Skills proposed by agents and approved by you | Enforced isolation between workspaces (milestone 6) |
| The service under launchd on macOS | Workflows (milestone 7), running on a server (milestone 10) |

## How these docs are organised

### Start here

[Installation](https://wheems.dev/docs/installation/) and the [Quick start](https://wheems.dev/docs/quick-start/): from nothing to a first reply from your chief of staff.

### Connecting Slack

[Every step in Slack](https://wheems.dev/docs/slack/): the app, its scopes, the tokens, who may talk to agents, channels and threads.

### Concepts and guides

[Concepts](https://wheems.dev/docs/concepts/), then the [knowledge base](https://wheems.dev/docs/knowledge-base/), [skills](https://wheems.dev/docs/skills/), [the service](https://wheems.dev/docs/service/) and [engines](https://wheems.dev/docs/engines/).

### Reference

Every key in the [configuration](https://wheems.dev/docs/reference/configuration/) and every [command and flag](https://wheems.dev/docs/reference/cli/).

Stuck? [Troubleshooting](https://wheems.dev/docs/troubleshooting/) lists each check `wheems doctor` makes and what to do when it fails. The [FAQ](https://wheems.dev/docs/faq/) answers the questions people ask first.

Every page is also available as Markdown, for you or your agents, at the same address ending in `.md`, such as [/docs/slack.md](https://wheems.dev/docs/slack.md). [llms.txt](https://wheems.dev/llms.txt) lists them all.

- [Install Wheems](https://wheems.dev/docs/installation/): Requirements, installing the wheems command, and checking it with wheems doctor.