Rendered preview

angel

Angel brings a second model into Pi when a decision needs independent investigation rather than another quick answer.

Use it for hard diagnoses, competing explanations, architectural choices, or uncertainty before you commit to an approach.

Start here

Configure an advisor for each executor model you want Angel to support, then start or restart Pi.

{
  "angel": {
    "pairs": [
      {
        "executor": "provider/working-model",
        "advisor": "provider/advisor-model"
      }
    ]
  }
}

In Pi, ask /angel <question>.

/angel Which explanation best fits this failing integration test?

Angel investigates in a separate child session and returns advice in Pi.

It can inspect relevant project files and retrieve parent-session evidence on demand.

Angel is available only while the current model matches a configured pair and authentication for its advisor is available.

During work

Your active agent can also call Angel when independent advice would improve its next decision.

After the same eligible tool call fails in two separate turns, Angel automatically asks the advisor to diagnose the repeated failure before the agent continues.

Nothing needs invoking for this recovery path.

Angel's advice appears in the conversation, with its child session available through Pi's normal session browser when you need the full investigation.

Use /angel off to disable both direct consultations and automatic recovery for the current session.

Use /angel on to enable it again, or /angel cancel to stop an active consultation.

Settings

Set angel.pairs in Pi settings to map executor models to advisor models.

A bare advisor model ID uses the executor's provider.

thinkingLevel controls the advisor's requested thinking level and defaults to max.

subagentExtensions controls extra extension sources available to the advisor, defaulting to "none".

Use "all" for enabled Pi extensions, or Pi package sources such as "./extensions/research" or "npm:@example/pi-research".

Relative sources resolve from the session working directory, like Pi's -e option; bare extension nicknames are not registry lookups.

Only tools marked with annotations.readOnlyHint: true are available to Angel, alongside its read-only built-ins. Indirect calls follow the same policy; annotations are author claims, not an OS sandbox.

enabled: false starts new sessions with Angel disabled.

Settings can come from trusted project .pi/settings.json or user settings, with trusted project values taking precedence.

See Installation.

Reference

Commands

Command	Purpose
/angel	Ask Angel a question directly, or enable/disable it for this session

Setting names

Setting
angel

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
angel.pairs
angel.pairs[].executor
angel.pairs[].advisor
angel.enabled
angel.thinkingLevel
angel.subagentExtensions

Changelog.

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

# angel

Angel brings a second model into Pi when a decision needs independent investigation rather than another quick answer.

Use it for hard diagnoses, competing explanations, architectural choices, or uncertainty before you commit to an approach.

![angel demo: the executor asks the advisor model a design question, the advisor reads the code and answers, the footer shows the route](assets/demo.gif)

## Start here

Configure an advisor for each executor model you want Angel to support, then start or restart Pi.

```json
{
  "angel": {
    "pairs": [
      {
        "executor": "provider/working-model",
        "advisor": "provider/advisor-model"
      }
    ]
  }
}
```

In Pi, ask `/angel <question>`.

```text
/angel Which explanation best fits this failing integration test?
```

Angel investigates in a separate child session and returns advice in Pi.

It can inspect relevant project files and retrieve parent-session evidence on demand.

Angel is available only while the current model matches a configured pair and authentication for its advisor is available.

## During work

Your active agent can also call Angel when independent advice would improve its next decision.

After the same eligible tool call fails in two separate turns, Angel automatically asks the advisor to diagnose the repeated failure before the agent continues.

Nothing needs invoking for this recovery path.

Angel's advice appears in the conversation, with its child session available through Pi's normal session browser when you need the full investigation.

Use `/angel off` to disable both direct consultations and automatic recovery for the current session.

Use `/angel on` to enable it again, or `/angel cancel` to stop an active consultation.

## Settings

Set `angel.pairs` in Pi settings to map executor models to advisor models.

A bare advisor model ID uses the executor's provider.

`thinkingLevel` controls the advisor's requested thinking level and defaults to `max`.

`subagentExtensions` controls extra extension sources available to the advisor, defaulting to `"none"`.

Use `"all"` for enabled Pi extensions, or Pi package sources such as `"./extensions/research"` or `"npm:@example/pi-research"`.

Relative sources resolve from the session working directory, like Pi\'s `-e` option; bare extension nicknames are not registry lookups.

Only tools marked with `annotations.readOnlyHint: true` are available to Angel, alongside its read-only built-ins.
Indirect calls follow the same policy; annotations are author claims, not an OS sandbox.

`enabled: false` starts new sessions with Angel disabled.

Settings can come from trusted project `.pi/settings.json` or user settings, with trusted project values taking precedence.

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

## Reference

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

| Command | Purpose |
| --- | --- |
| `/angel` | Ask Angel a question directly, or enable/disable it for this session |

### Setting names

| Setting |
| --- |
| `angel` |

#### 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 |
| --- |
| `angel.pairs` |
| `angel.pairs[].executor` |
| `angel.pairs[].advisor` |
| `angel.enabled` |
| `angel.thinkingLevel` |
| `angel.subagentExtensions` |
<!-- config:end -->

[Changelog](./CHANGELOG.md).