@laloomery/pi-weave-ext

pi extension that turns the current session into project documents maintained by /weave.

@laloomery/pi-weave-ext adds a slash command to pi. It reads the current saved session, extracts the relevant information, then produces the fragments requested by targets.yaml. Documents are written to the session's working directory.

The model only reorganizes content brought by the session according to your instructions: it must not invent facts.

Requirements

• Node.js 22.19.0 or later;
• pi with @earendil-works/pi-coding-agent 0.82 or later.

Loading the extension

From a clone of the repository:

pi -e /path/to/pi-weave-ext/index.ts

The extension uses the SDK of the pi instance hosting it. Its processing dependencies ship with the package.

Using /weave

In an interactive or RPC pi session:

/weave [--targets path/to/targets.yaml] [--model provider/id] [--dry-run]

Options:

• --targets <path>: overrides the default file, <cwd>/targets.yaml. A relative path is resolved from the current working directory; an absolute path is accepted.
• --model <provider/id>: chooses the model responsible for writing the fragments. This option takes priority over the model setting.
• --dry-run: generates the fragments without writing any file.

Before starting, the extension waits for pi to be idle. In the TUI, it then displays a per-target summary: written, skipped, blocked, simulated, or errored. The writing window cannot be cancelled with Escape, because pi provides no cancellation signal to the command handler.

Guards before writing

/weave warns and starts no processing if:

• the session is ephemeral and has no saved file yet — send a message first;
• the project is not marked as trusted in pi;
• the targets file is missing;
• no model is provided via --model or configuration;
• the model spec is not in provider/id format.

Extension settings

Optionally create weave.settings.json. The extension looks for the first readable file in this order:

1. <cwd>/.pi/weave.settings.json;
2. <pi agent directory>/weave.settings.json.

Project configuration therefore takes priority over global configuration. A missing file is ignored. An invalid JSON file produces a warning and the search continues to the next location; execution remains possible if a model is provided otherwise.

The pi scribe is isolated by default, so native models require no extension configuration. An extension provider requires an explicit completeOptions.extensionsPaths allowlist. It replaces automatic discovery, so list every extension needed by the scribe session.

{
  "model": "9router/kr/claude-haiku-4.5",
  "fragmentCleanupPatterns": ["\\n*MODEL_ARTIFACT[^\\n]*$"],
  "extractOptions": {
    "subagentToolNames": ["Agent"],
    "askUserQuestionToolNames": ["ask_user_question"]
  },
  "completeOptions": {
    "extensionsPaths": ["/path/to/pi-9router-ext"]
  }
}

Key	Role
model	Default writing model, in provider/id format. Required if /weave does not receive --model.
fragmentCleanupPatterns	Regex sources applied to each model response before writing, not to transcript extraction. An invalid regex reports a warning. Use this only to remove output artifacts from an explicitly allowed extension.
extractOptions.subagentToolNames	Names of subagent tools whose results should be extracted from the session. No default: if this key is absent, no subagent result is extracted.
extractOptions.askUserQuestionToolNames	Names of tools whose structured user answers should be extracted. No default: if this key is absent, no structured answer is extracted.
completeOptions.extensionsPaths	Exhaustive pi extension allowlist for the isolated writing session. A native model needs no entry; an extension provider needs its source or path.

The host and sdkPath settings do not apply to this extension: pi already provides the SDK and the host.

targets.yaml file

By default, /weave expects <cwd>/targets.yaml. Use --targets to choose another file; a relative path is resolved from the current working directory.

The global targets.yaml reference describes its syntax, write modes, skip_when, backups, deduplication, and target design recommendations.

Limitations

• /weave only documents changes and information from the current session; it is not an audit of the existing document or of the project.
• An explicitly allowed pi extension may add artifacts to the model response; configure fragmentCleanupPatterns only when that cleanup is required.

License

See the monorepo.