# Set up models and preferences

[Docs home](../README.md) · [All commands](commands.md) · [Safety and permissions](data-and-permissions.md)

## Settings

Use `/bro config` for the layered Global and Features menu. Its editable pages retain the existing backend/model/effort pickers, save checks and per-capability overrides. Changes save immediately. Esc inside a
picker cancels that pick; Esc on the settings screen closes it, keeping
whatever was already saved. If the terminal becomes too small, config blocks
hidden actions; Esc closes config even if a picker was open, after pending saves
finish. A failed save cancels that close and shows its error inline; if the error
alone makes config too small, any other key clears it so you can try again. `/bro mode` changes the mode directly (**M** in an explanation
tries another mode without saving it), and `/bro help` shows the active settings
and file path.

### Config navigation

```text
/bro config
├── Global
│   ├── Default backend, model and effort
│   ├── Preferences (opens the existing shared editor)
│   └── Doctor (runs only when selected)
└── Features
    ├── Simplify — Explain override and default brief/balanced/faithful mode
    ├── Show — Show override and default turn count
    ├── BTW — backend/model/effort override
    ├── Guided Review — Review override
    ├── Advisor — override and persistent steering editor
    ├── Elevate — inherits BTW (informational)
    ├── Grill Me — inherits BTW (informational)
    └── Remember Me — inherits BTW (informational)
```

The BTW page shows what the selected backend can do in conversation-only mode,
and reminds users that `/mode` **inside BTW** switches to full workspace access.
Guided Review shows its selected backend's real inspection limits: strict file
tools on some backends, sandboxed shell on others, and Agy's ability to write
within the captured checkout. These are explanations of existing behavior,
not a new permission switch or an extra compatibility restriction. See
[backend access and retention](data-and-permissions.md#backends-access-and-retention).

Enter drills down. Esc backs out or closes at root; editors use their existing
save/cancel behavior. Opening Config does **not** run Doctor, touch a model, or
modify settings. Current selected models and overrides remain visible in the
existing editing pages. The old `/bro doctor`, `/bro preferences` and
`/bro advisor-steer` shortcuts remain callable.

Architecture Docs inherits the **BTW** backend/model/effort selection. It uses a fresh restricted file-inspection call and does not alter the BTW thread. See [Architecture Docs](../features/architecture.md).

Elevate inherits the **BTW** backend/model/effort selection. There is no separate Elevate setting in this release. See the [Elevate guide](../elevate.md).

Settings live in this user-editable file, created when the extension loads
(under `$PI_CODING_AGENT_DIR` instead when that is set):

```text
~/.pi/agent/bro-settings.json
```

```json
{
  "version": 2,
  "default": { "backend": "agy", "model": "gemini-3.7-flash", "effort": "low" },
  "mode": "balanced",
  "showTurns": 1,
  "overrides": {
    "explain": { "backend": "claude", "model": "sonnet", "effort": "medium" },
    "advisor": { "backend": "grok", "model": "grok-4.7", "effort": "high" },
    "review": { "backend": "pi", "model": "anthropic/claude-sonnet-4-5", "effort": "high" }
  }
}
```

Bro reads the file again before each request, so manual edits apply next time.

- Each selection is one atomic backend/model/effort choice. An override pins
  its own complete selection and ignores the shared default, even when it
  happens to match it; select **Default** in `/bro config` to inherit again.
  Omitted overrides inherit `default`.
- `effort` must be one the backend offers (`default` omits it and lets the
  model decide). Agy selections are normalized against Agy's installed model
  catalog. Claude, Grok, Codex, and Muse accept seeded or custom model IDs; a model/effort
  combination the account does not support fails with the backend's own error
  instead of silently falling back. **Pi** selections are a `"<provider>/<id>"` pair
  from your Pi model catalog, chosen from your configured scoped models
  (`enabledModels`, falling back to every model with configured credentials).
  Explicit Pi efforts are clamped to the model's supported reasoning levels; the
  picker's own step 1 chooses the backend and step 2 the model.
- `mode` is `brief`, `balanced` (the default), or `faithful`. `showTurns` is
  the default number of turns `/bro show` draws (default 1); `/bro show
  <n-turns>` overrides it for one run.
- `PI_BRO_MODEL` picks the initial Agy model only when Bro creates a missing
  settings file, for example `PI_BRO_MODEL=gemini-3.7-flash-low pi`.
- Older flat settings files (root `model`/`effort`) still load and mean Agy.

## Preferences

Tell Bro about yourself and how you like answers. Bro adds what you write to
every explain, `/bro show`, `/bro btw`, `/bro elevate`, and Guided Review prompt as a labelled section,
alongside its own instructions. It never replaces them: modes, **M**, and the
source rules keep working. The advisor never receives your preferences; use
`/bro advisor-steer` for it.

Run `/bro preferences` to edit them: **Ctrl+S** saves, **Ctrl+K** deletes the
file, **Ctrl+C** copies, and **Esc** closes without saving. The first time,
the editor opens with this starter text, which is not saved until you press
**Ctrl+S**:

```md
## About me
I'm an overworked white-collar worker, and so are my colleagues. By the end of a
hard day our brains are fried and we can only handle simple language, no matter
how sharp we are at our best.

## How I like answers
- Explain it like I'm a simpleton: plain, everyday words.
- Go easy on analogies. No forced ones.
```

You can also edit the file directly (under `$PI_CODING_AGENT_DIR` instead when
that is set):

```text
~/.pi/agent/bro-preferences.md
```

- **Free-form**: no placeholder or structure is required. Bro re-reads the
  file on every request, so edits apply next time. A missing or empty file
  means no preferences, and Bro's prompts are then exactly the built-in ones.
- **What preferences can change**: wording, tone, technical depth, length in
  BTW, and the answer language. If you name a language, code, commands, paths,
  names, and numbers still stay exactly as written. In `/bro show`,
  preferences only change wording and language. Guided Review also receives preferences for explanation/answer wording; they do not override its evidence or review rules. A per-run choice (the mode,
  **M**, a Show steering query, or what a BTW/review question asks for) wins over a
  standing preference.
- **Limit**: 4,000 characters, because the text goes with every request. A
  longer file stops explain, Show, BTW, and Guided Review with an error until you trim it;
  Bro never cuts it silently. `/bro doctor` reports the problem, and the
  editor still opens the file so you can fix it.
- **BTW threads**: when your preferences change, the next side question starts
  a fresh backend session that is caught up on the thread, so old preferences
  don't linger.

`bro-prompt.md`, the full prompt template from earlier versions, is no longer
read. Move what you want to keep into `/bro preferences`, and choose
`/bro mode brief` for the original ELI-simpleton instruction.

## Remember Me

`/bro remember-me` manages approved personal memories in `bro-memories.json` in the same user agent directory. Each entry has a stable ID, a scan-first short statement, and optional scope, exceptions, uncertainty and source context in an expanded view. The agent-facing `about_user` tool reads them on demand. `/bro preferences` remains a separate legacy file; no automatic migration or duplicate injection occurs. See [Remember Me](../remember-me.md).