# Engines and accounts

> Run agents in Claude Code, Codex or opencode, choose models and permission levels, and connect the accounts that pay for them.

An **engine** is the agent CLI an agent runs in: Claude Code, Codex or opencode, unchanged. An **account** is what pays for its model. This page covers installing and signing in each engine, choosing a model, permission levels, and accounts.

## The engines

| Engine | `engine:` | Instructions file | Default model | Signs in with |
| --- | --- | --- | --- | --- |
| Claude Code | `claude-code` | `CLAUDE.md` | `claude-opus-5-5` | A Claude subscription |
| Codex | `codex` | `AGENTS.md` | `gpt-6.1-sol` | A ChatGPT subscription |
| opencode | `opencode` | `AGENTS.md` | `opencode/big-pickle` | OpenRouter, a provider's key, or its free models |

Every engine runs in its own terminal in Herdr core, where you can watch it with `hc attach` and type into it.

## Installing and signing in

`wheems setup` → **Engines** shows each engine's version and whether it's signed in. Pick one: setup shows the install command and asks before running it, then runs the engine's own sign-in on your terminal, so you log in yourself. To do it by hand:

| Engine | Install | Sign in |
| --- | --- | --- |
| Claude Code | `npm install -g @anthropic-ai/claude-code` | `claude auth login` |
| Codex | `npm install -g @openai/codex` | `codex login` |
| opencode | `npm install -g opencode-ai` | `opencode providers login` |

opencode's free models need no sign-in.

### Trusting the workspace folder

Claude Code and Codex ask once whether to trust a new folder, and nobody can answer that from Slack. Open the engine in each new workspace folder once and say yes:

```bash title="Terminal"
cd ~/wheems/workspaces/acme
claude                 # or: codex --no-daemon
```

`wheems setup` offers to do this when it creates a workspace, and `wheems init` prints the commands. `wheems doctor` checks it:

```text title="Output"
Agents
  ! acme folder: Claude Code hasn't been told to trust the workspace folder, so its first session will wait for that answer at the Mac
      Open the engine in that folder once and say yes, or run wheems setup.
```

opencode doesn't ask.

## Choosing the engine and model

Each agent's front matter names its engine, model and account:

```markdown title="~/wheems/workspaces/acme/agents/chief-of-staff.md"
---
engine: codex
model: gpt-6.1-sol
account: chatgpt-subscription
permissions: auto
---
```

- `model` is the engine's own model id, passed to it as is: `claude-opus-5-5` for Claude Code, `gpt-6.1-sol` for Codex, `openrouter/x-ai/grok-5` or `opencode/big-pickle` for opencode.
- `wheems init <id> --engine codex --model gpt-6.1-sol` sets them when creating a workspace. Without `--model`, the engine's default is used.
- Restart the service after changing them.

## Permission levels

`permissions` says how much an agent may do without asking:

| Level | Meaning | Claude Code | Codex | opencode |
| --- | --- | --- | --- | --- |
| `ask` (default) | The engine's normal prompts | (none) | (none) | (none) |
| `auto` | The engine decides routine actions, and asks for risky ones | `--permission-mode auto` | `--approve-for-me` | `--auto` |
| `skip` | Never asks | `--dangerously-skip-permissions` | `--dangerously-bypass-approvals-and-sandbox` | `--auto` |

A prompt means someone has to answer it at the Mac. In Slack you'd see:

```text title="Slack"
Wheems: The agent is waiting for an answer at the Mac, such as a permission prompt: `hc attach t7`.
```

So a chief of staff you talk to from your phone usually runs on `auto`, which is what `wheems init` writes.

> **Planned · milestone 3:** Approval buttons in Slack, so you can answer from your phone, arrive in milestone 3. Until then, answer prompts at the Mac with `hc attach`.

## What Wheems writes for the engine

When Wheems starts an agent, it writes the engine's instructions file in the workspace folder: `CLAUDE.md` for Claude Code, `AGENTS.md` for Codex and opencode. It holds, in order:

1. the agent's own instructions, from its Markdown file;
2. Wheems's built-in instructions: talking to the person, `wheems reply`, writing notes, searching the knowledge base and proposing skills;
3. what the agent should know at launch: `about-you.md` and the workspace's brief.

Don't edit this file: it's rewritten at every launch and ignored by git. Edit the agent's file in `agents/` instead.

## How Wheems follows each engine

| Engine | Follows each turn by | Resumes a conversation by |
| --- | --- | --- |
| Claude Code | Its status in Herdr, and its transcript | The session id Wheems gives it |
| Codex | Its status in Herdr, and its session record | The id it chose, found from the session's folder, start time and first message |
| opencode | Its answers | The id it chose, found the same way |

Answers are always read from the engine's own record of the conversation, never from the screen.

## Accounts

Accounts are declared once in `install.yaml`, and each workspace lists the ones its agents may use:

```yaml title="~/wheems/install.yaml"
accounts:
  claude-subscription: { driver: claude }
  chatgpt-subscription: { driver: chatgpt }
```

```yaml title="~/wheems/workspaces/acme/workspace.yaml"
accounts: [claude-subscription, chatgpt-subscription]
```

An agent's `account` must be one of its workspace's `accounts`, and each workspace's must exist in `install.yaml`. `wheems validate` checks both. `wheems init` and setup add the right account for the engine you choose:

| Engine | Account name | `driver` |
| --- | --- | --- |
| Claude Code | `claude-subscription` | `claude` |
| Codex | `chatgpt-subscription` | `chatgpt` |
| opencode | `opencode` | `opencode` |

Today an account is a label: the engine uses whatever it's signed in with.

> **Planned · milestone 5:** API-key accounts (OpenRouter, Anthropic's API) with their own keys, and `max_sessions` per account so one subscription isn't exhausted, arrive in milestone 5.

## Usage and terms

Running Claude Code and Codex on your own subscription, for yourself, is what they're for. Agents draw on the same usage limits as your own sessions, and each workspace keeps up to four sessions running. Check your provider's terms before running Wheems for other people.

## What leaves your Mac

Agents run on their model providers: Anthropic for Claude Code, OpenAI for Codex, whichever provider opencode is set up with. Those providers see each conversation and what agents load or read, including `about-you.md` and the brief. Search by meaning with Ollama is local.