angel # 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 `. ```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 ### 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](./CHANGELOG.md).