---
title: Extension reference
type: overview
status: active
updated: 2026-08-19T22:43:06Z
description: Reference the shipped extension surface.
owner: locus-pi maintainers
tags: [extensions, reference]
---

# Extension reference

`package.json#pi.extensions` is the authoritative list of what Pi loads and registers. The table is a readable index; each manifest remains the machine-owned declaration.

<!-- locus:extensions:start -->
<!-- Generated by `npm run build:catalogs`. Edits between these markers are overwritten. -->

| Extension             | Tools                                         | Commands                                                                                                      | Hooks                                                                                    | Risk     | Manual                                                                                    |
| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `agents`              | `spawn_agent`                                 | `agent list`, `agent inspect`, `agent run`, `agent observe`, `agent summary`, `agent drill`, `agent ps`, `ps` | `session_start`, `session_shutdown`, `before_agent_start`, `input`                       | high     | [`extensions/agents/README.md`](../extensions/agents/README.md)                           |
| `ask-user-question`   | `ask`                                         | —                                                                                                             | —                                                                                        | medium   | [`extensions/ask-user-question/README.md`](../extensions/ask-user-question/README.md)     |
| `ast-structural-edit` | `ast_grep`, `ast_edit`, `resolve`             | —                                                                                                             | —                                                                                        | high     | [`extensions/ast-structural-edit/README.md`](../extensions/ast-structural-edit/README.md) |
| `model`               | —                                             | `model-roles`, `effort`                                                                                       | `session_start`, `input`                                                                 | medium   | [`extensions/model/README.md`](../extensions/model/README.md)                             |
| `status-line`         | —                                             | —                                                                                                             | `session_start`, `session_before_compact`, `session_compact`, `session_shutdown`         | low      | [`extensions/status-line/README.md`](../extensions/status-line/README.md)                 |
| `workflows`           | `workflow`, `workflow_check_source`, `fusion` | `workflows`, `workflow-stop`, `fusion`                                                                        | `session_start`, `session_shutdown`, `input`, `turn_end`, `agent_settled`, `tool_result` | critical | [`extensions/workflows/README.md`](../extensions/workflows/README.md)                     |

<!-- locus:extensions:end -->

## Direct feature dependencies

Shared imports through `extensions/_shared/` are infrastructure dependencies, not extension-to-extension dependencies. The current direct feature graph is:

- `agents → workflows`

The other extensions do not directly import another feature directory.

## Reading a manifest

`schemas/extension-manifest.schema.json` is the whole field list, and `npm run check` validates every manifest against it, so a field the schema does not declare is rejected rather than ignored. The fields are:

- `id` — extension identity;
- `provides` — public tools, commands, hooks, and shortcuts;
- `permissions` — declared filesystem, subprocess, network, browser, model, and UI capabilities. This is a review declaration; the package grants no capability from it and the host is not sandboxed by it;
- `risk` — review severity, not a sandbox guarantee;
- `runtimeRequirements` and `stateUsed` — detailed execution and persistence contracts;
- `uiLifecycle` — per-command and per-tool UI and persistence taxonomy, for extensions that expose a surface;
- `docsPath` — co-located extension manual;
- `tests` — paths to the implementation evidence.

A manifest declares no versioning: the npm package version covers that. `package.json#pi.extensions` decides what Pi loads and registers.

A manifest describes the intended contract. Source and tests remain necessary evidence that the implementation matches it.