# Concepts

> The parts of Wheems and how they relate, from the install and workspaces to agents, skills, the knowledge base, tasks, routines and workflows.

Wheems has a small number of parts. This page explains each one in a few lines, says whether it's built, and links to where it's covered in full.

| Concept | In one line | Status |
| --- | --- | --- |
| [Install](#the-install) | Your config, in a git folder | Built |
| [Workspace](#workspaces) | One business or area of life | Built (isolation in milestone 6) |
| [Chief of staff](#the-chief-of-staff) | The agent you talk to in each workspace | Built |
| [Agents and engines](#agents-and-engines) | A Markdown file, run in Claude Code, Codex or opencode | Built |
| [Conversations](#conversations) | One Slack thread, one engine session | Built |
| [Knowledge base](#the-knowledge-base-and-search) | Notes filed into pages, searched by keyword and meaning | Built |
| [Skills](#skills) | How to do a recurring task, versioned and approved by you | Built |
| [The service](#the-service) | Connects Slack to agents, in the background | Built |
| [Drivers](#drivers) | Every extension point, behind a contract | Built |
| [Projects](#projects) | A body of work inside a workspace, with its own lead | Planned · milestone 4 |
| [Tasks](#tasks) | The one hand-off between agents | Planned · milestone 5 |
| [Routines](#routines) | A schedule, an agent and a skill | Planned · milestone 5 |
| [Workflows](#workflows) | A fixed series of steps with gates and checks | Planned · milestone 7 |

## The install

You install Wheems once per person. **The install** is a folder, `~/wheems` by default, that holds everything you configure. It's a git folder, never pushed anywhere, so every change to every page and config file is kept.

```text
~/wheems/
├── install.yaml        accounts, connections, knowledge settings
├── about-you.md        every agent in every workspace reads it
├── library/skills/     every version of every skill
├── workspaces/<id>/    one folder per workspace
└── .wheems/            running state, never committed
```

`install.yaml` holds what every workspace shares: the accounts that pay for models, the connections to Slack and other services, who may talk to agents, and how the knowledge base is searched. See the [Configuration reference](https://wheems.dev/docs/reference/configuration/).

## Workspaces

A **workspace** is an entity with its own people, knowledge and confidentiality: your personal life, a business, a client. Each has its own folder, chief of staff, agents, chat channel, knowledge base and search index.

Make something a separate workspace when it has different people, should keep its knowledge private, or may be handed to someone else one day.

```text
workspaces/acme/
├── workspace.yaml         its name, accounts, chat channel, knowledge settings
├── agents/
│   └── chief-of-staff.md  the agent you talk to
├── skills.yaml            the skills it uses, pinned to library versions
└── knowledge/
    ├── brief.md           a short summary every agent here loads at launch
    ├── inbox/             notes land here
    ├── notes/             filed notes, kept as the sources
    ├── pages/             the knowledge base, one topic per page
    └── reports/           nightly: contradictions and stale pages
```

Create one with `wheems setup` → **Workspaces**, or `wheems init <id>`.

> **Planned · milestone 6:** Today workspaces are separate folders, but not walls: an agent in one workspace could read another's files if it went looking. Enforced isolation, with permission rules that deny other workspaces, arrives in milestone 6.

## The chief of staff

Each workspace has one **chief of staff**: the agent you talk to from Slack. It's an ordinary agent file, `agents/chief-of-staff.md` by default, named by `chief_of_staff` in `workspace.yaml`. Today it's the only agent the service starts. Later milestones let it route work to project leads and hand jobs to other agents as tasks.

## Agents and engines

An **agent** is a Markdown file: YAML front matter saying which engine, model and account it runs on, then its instructions.

```markdown title="~/wheems/workspaces/acme/agents/chief-of-staff.md"
---
description: The one entry point for Acme, aware of everything going on in it.
engine: claude-code
model: claude-opus-5-5
account: claude-subscription
permissions: auto
---

# Acme: chief of staff

You are the chief of staff for Acme. Be brief. Lead with the answer.
```

An **engine** is the agent CLI it runs in, unchanged: Claude Code, Codex or opencode. An **account** is what pays for the model, such as your Claude subscription. When Wheems starts an agent, it writes the engine's instructions file (`CLAUDE.md` or `AGENTS.md`) in the workspace folder from the agent's instructions, Wheems's built-in instructions, `about-you.md` and the brief.

See [Engines and accounts](https://wheems.dev/docs/engines/).

## Conversations

Each message you send in Slack starts a **conversation**, and replies in its thread carry it on. Each conversation is its own engine session, running in a terminal in Herdr core, where you can watch it or take over with `hc attach`. A session that was stopped is resumed, with its history, when you next reply.

See [Connecting Slack](https://wheems.dev/docs/slack/#conversations-and-threads).

## The knowledge base and search

Agents never write the knowledge base themselves. They write **notes**, and a built-in **filer** agent turns notes into **pages**, one topic per page. Wheems checks the filer's work in code before anything is committed. Overnight, a **tidy** reports contradictions and stale pages and refreshes each workspace's **brief**.

![An agent writes a note with wheems note, and it lands in knowledge/inbox/. The filer files it into knowledge/pages/, one topic per page, checked and committed, and keeps the note itself in knowledge/notes/ as a source.](https://wheems.dev/docs/diagrams/knowledge-flow.svg)

Agents search before answering about past work, with `wheems kb search`, by keyword and, with a local embedding model, by meaning.

See [Knowledge base and search](https://wheems.dev/docs/knowledge-base/).

## Skills

A **skill** is how to do a task that comes up again: the steps, the checks, and what to watch for, in the [Agent Skills](https://agentskills.io) `SKILL.md` format. The install's **library** keeps every version of every skill. A workspace pins the versions it uses, and agents propose new skills, which reach the library only when you approve them with `wheems review`.

See [Skills](https://wheems.dev/docs/skills/).

## The service

**The service** runs in the background under launchd. It holds the Slack connection, starts a session for each conversation, posts answers, files notes, keeps the search index current and runs the nightly tidy. Agents reach it through the `wheems` command, over a private socket.

See [Running as a service](https://wheems.dev/docs/service/).

## Drivers

Every extension point is a **driver**: a small TypeScript contract with built-in drivers behind it, as in Laravel. Adding Discord or another agent CLI means writing one driver, not changing the core.

| Driver type | What it does | Built in |
| --- | --- | --- |
| Runtime | Starts, sends to, reads and waits on agent sessions | Herdr core |
| Engine | Runs an agent in a given CLI | Claude Code, Codex, opencode |
| Channel | Sends and receives messages, threads and reactions | Slack (Socket Mode) |
| Embeddings | Turns text into vectors for searching by meaning | Ollama |
| Vector store | Keeps vectors and finds the nearest | SQLite |

Each driver type has a contract test suite, exported as `wheems/testing`, that any driver of that type must pass. Plugins installed from npm, and `make:` commands to scaffold them, are planned for milestone 11.

## Projects

> **Planned · milestone 4:** Not built yet.

A **project** is any body of work inside a workspace: customer support, reviews, sales leads, a website. Each will have its own knowledge base, and optionally a **lead** agent you talk to in the project's own Slack channel. The workspace's chief of staff will search across projects and send jobs to their leads.

Projects keep context clean; they aren't confidentiality walls. If something needs secrecy or different people, make it a workspace.

## Tasks

> **Planned · milestone 5:** Not built yet.

A **task** is the one hand-off between agents: a written brief to an agent in a fresh session, and a written result back. A chief asking a lead, a lead handing work to a worker, a routine's run and a workflow step will all be tasks. Each task is evaluated: acceptance criteria checked in code, a judge where code can't check, and your feedback.

## Routines

> **Planned · milestone 5:** Not built yet.

A **routine** is a trigger, one agent and one skill, run as a single task: a morning brief every weekday at 7, for example. When the chief of staff notices you asking for the same thing again and again, it will offer to make it a routine.

## Workflows

> **Planned · milestone 7:** `workspaces/<id>/workflows/*.yaml` files are already validated, so config written now keeps working, but nothing runs them yet.

A **workflow** is a fixed series of steps, with the order, approvals and checks run by Wheems and agents working only inside steps. Use one when a job has several touchpoints, acts on the outside world (sending, publishing, spending), or needs approvals along the way. A new workflow starts in **shadow mode**, proposing each action for your approval, and its steps graduate to acting alone as their results earn it.

| | Routine | Workflow |
| --- | --- | --- |
| Shape | One agent, one skill, one task | Many steps, gates and checks |
| Order | Up to the agent | Fixed by Wheems |
| Good for | A single output you read, such as a brief | Sending, publishing, money, customers, hand-offs |
| Milestone | 5 | 7 |