Rendered preview

masks

Masks let you switch Pi into named working modes instead of repeatedly changing model, reasoning level, tools, and instructions. Use a mask for jobs like read-only review, planning, or a preferred model setup.

Start here

Configure at least one mask in ~/.pi/agent/settings.json. Then press alt+m or run /masks to choose it. Run /masks <name> or use that mask's optional shortcut to switch directly. Pi's footer shows the selected model and thinking level.

{
  "masks": {
    "items": [
      {
        "name": "review",
        "model": "provider/model-from-pi",
        "thinkingLevel": "medium",
        "tools": ["read", "grep", "find", "ls"],
        "instructions": "Review only. Report findings; do not edit files."
      }
    ]
  }
}

Replace provider/model-from-pi with a model ID available in Pi's /model picker. Each mask needs a unique name, a provider/model, and a thinking level. Optional tools replace Pi's active tools when that mask is selected. Optional instructions guide Pi for later turns until another mask replaces them. Choose tool lists deliberately because a manual mask change remains active.

Prompt-specific masks

A prompt template can select a mask only for that prompt and its tool calls. Add mask: review to its frontmatter. The prior model, tools, and instructions return after the prompt finishes.

---
mask: review
---
Review the current change.

If you submit such a prompt while Pi is busy, Masks queues it for later. Run /masks-cancel to discard queued masked prompts.

Set masks.pickerShortcut to change alt+m. Masks use user settings only, not project settings. After rebuilding an update or changing settings, restart Pi.

Installation

Reference

Commands

Command	Purpose
/masks	Switch model and thinking mask
/masks-cancel	Cancel deferred masked prompts without interrupting the current run

Setting names

Setting
masks

Object fields

Paths below describe fields inside their parent settings object, not literal top-level keys. [] denotes an array element; see setup above for examples and defaults.

Field
masks.pickerShortcut
masks.items
masks.items[].name
masks.items[].model
masks.items[].thinkingLevel
masks.items[].shortcut
masks.items[].tools
masks.items[].instructions

Changelog.

<img src="assets/banner.svg" alt="masks" height="70">

# masks

Masks let you switch Pi into named working modes instead of repeatedly changing model, reasoning level, tools, and instructions.
Use a mask for jobs like read-only review, planning, or a preferred model setup.

![masks demo: alt+2 switches model and thinking, /masks plan equips read-only tools and planning rules, alt+1 restores everything](assets/demo.gif)

## Start here

Configure at least one mask in `~/.pi/agent/settings.json`.
Then press `alt+m` or run `/masks` to choose it.
Run `/masks <name>` or use that mask's optional shortcut to switch directly.
Pi's footer shows the selected model and thinking level.

```json
{
  "masks": {
    "items": [
      {
        "name": "review",
        "model": "provider/model-from-pi",
        "thinkingLevel": "medium",
        "tools": ["read", "grep", "find", "ls"],
        "instructions": "Review only. Report findings; do not edit files."
      }
    ]
  }
}
```

Replace `provider/model-from-pi` with a model ID available in Pi's `/model` picker.
Each mask needs a unique name, a `provider/model`, and a thinking level.
Optional tools replace Pi's active tools when that mask is selected.
Optional instructions guide Pi for later turns until another mask replaces them.
Choose tool lists deliberately because a manual mask change remains active.

## Prompt-specific masks

A prompt template can select a mask only for that prompt and its tool calls.
Add `mask: review` to its frontmatter.
The prior model, tools, and instructions return after the prompt finishes.

```markdown
---
mask: review
---
Review the current change.
```

If you submit such a prompt while Pi is busy, Masks queues it for later.
Run `/masks-cancel` to discard queued masked prompts.

Set `masks.pickerShortcut` to change `alt+m`.
Masks use user settings only, not project settings.
After rebuilding an update or changing settings, restart Pi.

[Installation](../../README.md#install)

## Reference

<!-- config:start -->
### Commands

| Command | Purpose |
| --- | --- |
| `/masks` | Switch model and thinking mask |
| `/masks-cancel` | Cancel deferred masked prompts without interrupting the current run |

### Setting names

| Setting |
| --- |
| `masks` |

#### Object fields

Paths below describe fields inside their parent settings object, not literal top-level keys.
`[]` denotes an array element; see setup above for examples and defaults.

| Field |
| --- |
| `masks.pickerShortcut` |
| `masks.items` |
| `masks.items[].name` |
| `masks.items[].model` |
| `masks.items[].thinkingLevel` |
| `masks.items[].shortcut` |
| `masks.items[].tools` |
| `masks.items[].instructions` |
<!-- config:end -->

[Changelog](./CHANGELOG.md).