Concepts

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.

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.

~/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.

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.

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>.

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.

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

---
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.

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.

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.

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.

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 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.

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.

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.

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.

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.

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.

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.

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.