# Wheems

> Wheems is an open-source, opinionated framework for running teams of AI agents: your own little cloud of helpers. 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 live in its own terminal on Herdr core (https://herdr.dev/core/) that you can watch or take over. A harness first, workflows when you want them.

Status (November 2026): early preview, version 0.0.3, published on npm as wheems (npm install -g wheems) under the Apache 2.0 licence. It isn't ready for real use yet: commands, config formats and where files live may change between releases. Milestones 0 to 2 of the roadmap's 0 to 11 are built: the CLI and `wheems doctor`, a chief of staff per workspace from Slack with one conversation per thread, the service under launchd on macOS, and the knowledge loop with search and skills. Slack is the only chat channel today; Telegram and email are planned (milestone 10). Projects, tasks, routines, workflows, enforced isolation between workspaces and running on a server are planned too; the roadmap below has each milestone. Every docs page below is available as Markdown, and https://wheems.dev/llms-full.txt has all of them in one file.

How Wheems is set up:

- One install per person: a git folder holding your config, a page about you, the skill library and your workspaces.
- A workspace for each business or area of life, with its own chief of staff, agents, chat channel and knowledge base.
- The knowledge loop: every session ends with a note; notes land in an inbox and are filed into the workspace's knowledge base, which agents search by keyword and by meaning.
- Scoped skills: skills live in a library; agents propose new ones, you approve them, and each workspace pins its own set.
- Guardrails outside the agent, not in its instructions: planned, with a broker for approvals (milestone 3), permissions that keep workspaces apart (milestone 6) and GitHub rules (milestone 9).

## Docs: Start here

- [Introduction](https://wheems.dev/docs/index.md): What Wheems is, who it's for, what works in the 0.0.3 early preview, and how these docs are organised.
- [Installation](https://wheems.dev/docs/installation.md): Requirements for Wheems, installing the wheems command with npm, and checking the machine with wheems doctor.
- [Quick start](https://wheems.dev/docs/quick-start.md): From nothing to a first reply from your chief of staff in Slack, with wheems setup, init, doctor and the service.

## Docs: Slack

- [Connecting Slack](https://wheems.dev/docs/slack.md): Create the Wheems Slack app from its manifest, connect its two tokens, allow people, bind channels and test it end to end.

## Docs: Concepts

- [Concepts](https://wheems.dev/docs/concepts.md): The parts of Wheems and how they relate, from the install and workspaces to agents, skills, the knowledge base, tasks, routines and workflows.

## Docs: Guides

- [Knowledge base and search](https://wheems.dev/docs/knowledge-base.md): How notes become knowledge base pages, what the filer and nightly tidy do, and how agents search by keyword and by meaning.
- [Skills](https://wheems.dev/docs/skills.md): How skills are written, versioned in the library and pinned per workspace, how agents propose them, and how you approve them with wheems review.
- [Running as a service](https://wheems.dev/docs/service.md): Install, check, restart and remove the Wheems service under launchd on macOS, read its log, and know when to restart it.
- [Engines and accounts](https://wheems.dev/docs/engines.md): Run agents in Claude Code, Codex or opencode, choose models and permission levels, and connect the accounts that pay for them.

## Docs: Reference

- [Configuration reference](https://wheems.dev/docs/reference/configuration.md): Every key in install.yaml, workspace.yaml, agent front matter and skills.yaml, with its type, default and an example, plus environment variables.
- [CLI reference](https://wheems.dev/docs/reference/cli.md): Every wheems command, argument and flag in version 0.0.3, from its own help output, with examples and what each prints.

## Docs: Help

- [Troubleshooting](https://wheems.dev/docs/troubleshooting.md): Every check wheems doctor makes, what each failure or warning means and how to fix it, plus common problems in Slack and the service.
- [Roadmap](https://wheems.dev/docs/roadmap.md): The milestones Wheems is built in, what each one brings, and where version 0.0.3 sits.
- [FAQ](https://wheems.dev/docs/faq.md): Short answers to the questions people ask first about Wheems, from cost and privacy to Linux, other chat apps and the early-preview status.

## Links

- [Home page](https://wheems.dev/): what Wheems is, how a request moves through a workspace, and the opinions
- [Docs](https://wheems.dev/docs/): the documentation as web pages
- [Weekly build log](https://wheems.dev/#updates): sign up for notes from the build every week
- [Mike Deeming on X](https://x.com/mikejdeeming): the builder, sharing the work in public

## Optional

- [All the docs in one file](https://wheems.dev/llms-full.txt): every page above, in order, as Markdown