Start here
Introduction
What Wheems is, who it's for, what works in the 0.0.3 early preview, and how these docs are organised.
On this page
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.
A harness first, workflows when you want them
Link to “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
Link to “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
Link to “How it fits together”- 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
wheemscommand 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
Link to “What works today”Version 0.0.3 is milestones 0 to 2 of the 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
Link to “How these docs are organised”Start here
Installation and the Quick start: from nothing to a first reply from your chief of staff.
Connecting Slack
Every step in Slack: the app, its scopes, the tokens, who may talk to agents, channels and threads.
Concepts and guides
Concepts, then the knowledge base, skills, the service and engines.
Reference
Every key in the configuration and every command and flag.
Stuck? Troubleshooting lists each check wheems doctor makes and what to do when it fails. The 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. llms.txt lists them all.