pi-forge

English | 简体中文 · Documentation

pi-forge lets you customize how Pi thinks and behaves. Presets bundle an ordered prompt Stack with tool/skill policy, Regex, and parameters; agent profiles apply a model, thinking level, and Preset as a reusable one-shot configuration.

Think of it as a character sheet and workbench for your AI agent.

Highlights

• Compose Pi's system prompt, conversation history, tools, skills, project context, and runtime data as ordered blocks and slots.
• Switch between coding, reviewing, writing, roleplay, and translation modes with one command.
• Save and apply complete model/thinking/Preset profiles.
• Enforce per-Preset tool policy and filter model-visible skills.
• Use immutable Preset parameters with the deterministic forge-v1 template engine.
• Apply deterministic regex transforms to outgoing prompts or finalized assistant messages.
• Edit Presets and profiles in a local browser UI and inspect the exact provider payload.
• Inspect prompt changes in the Preview dock: Preview compiles the live draft, Draft diff compares unsaved edits with disk, and Run diff compares recent provider turns. Git-style unified/split views include old/new line numbers, inline highlights, and changes-only/three-line/all-line context. Run metadata keeps chars/4 estimates separate from Pi's provider-reported prompt/cache usage and real cache-hit rate.
• Run an explicitly enabled profile as an experimental, approval-gated foreground subagent.

Install

pi-forge requires Node.js 22.19 or newer.

pi install npm:@zihanw/pi-forge

Restart Pi after installing or updating the extension. Pi supplies its SDK packages to extensions at runtime; pi-forge keeps exact Pi versions only for reproducible development and tests. See compatibility and setup for the supported/tested policy.

Five-minute start

1. Create a Preset

Create the default Preset from the default Pi mirror. The compatibility storage path remains .pi/forge/prompt-stacks/default.json in 0.5.3:

mkdir -p .pi/forge/prompt-stacks
cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json

If you installed from npm rather than cloning this repository, open /preset ui and create a new Preset; the editor starts with the same Pi-mirror layout.

Restart Pi or run:

/preset reload
/preset use default

default.json auto-activates when no Preset or restored session selection takes precedence.

2. Open the visual editor

/preset ui

The local editor can create, fork, validate, preview, import, export, and delete Presets. Its Agent profiles view manages one-shot model/thinking/Preset bundles. Writes require a trusted project. When @zihanw/pi-forge-subagents is installed, its schema-driven editor appears on the separate top-level Settings surface and persists to the optional package's subagents.json files.

3. Save a profile

Configure Pi normally, then capture and reuse the current settings:

/profile save reviewer
/profile use reviewer

A profile applies once. Later manual changes to the model or thinking level remain in effect until the profile is applied again; an active Preset continues enforcing its tool policy.

Session state for statuslines and scripts

While a Pi session is active, Forge publishes a small JSON file at:

~/.pi/agent/cache/forge/<URI-encoded-session-id>.json

The file is atomically replaced whenever the active Preset or last-applied profile changes, and is removed when that session shuts down. Its stable v1 shape is:

{
  "version": 1,
  "sessionId": "…",
  "preset": "project:default",
  "profile": null,
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

preset and profile are null when inactive. preset is a scoped resource key (project:<id> or global:<id>). Use /forge-state to display the same current JSON in Pi.

The basic model

A Preset is one JSON document. Its ordered composition section is the Stack:

Stack item	Purpose
Block	Static system, user, assistant, or hidden custom text
Slot	Runtime content such as tools, skills, project context, date/cwd, or chat history

The Preset also carries system mode (replace, append, or prepend), tool/skill policy, Regex, parameters, and extension references. During compilation, pi-forge expands the Stack, compiles forge-v1 templates over runtime.* / parameters.* / extensions.*, enforces tool policy, filters its skill listing, and applies enabled Regex rules.

Agent profiles reference an exact provider/model, thinking level, and Preset. They intentionally do not duplicate tool or skill policy—the referenced Preset remains the source of truth.

0.5.3 compatibility note. User-facing terminology now follows Preset → Stack. Storage and schema identifiers remain backward-compatible in this patch: .pi/forge/prompt-stacks/, "pi-forge.prompt-stack", profile field promptStack, /api/stacks, and internal PromptStack type names are unchanged. See the roadmap for the later storage/schema migration.

Start with these examples:

• Default Pi mirror keeps normal Pi behavior while making its sections movable.
• Minimal worker borrows the DeepSeek Harness Minimal shape using stock Pi tools: the exact one-line persona, chat history, and only bash plus edit, without replicating DSH shell/editor semantics.
• Regex hack pack demonstrates request-frequency outgoing redaction plus transcript-finalize scrubbing for two illustrative token shapes; it is not an exhaustive secret scanner.
• Custom system-status extension registers a trusted macro and slot.
• Fake-assistant direct-output experiment appends ordinary assistant text after chat history to test a model-specific reasoning shortcut; support varies by model/provider/endpoint and must be verified with an A/B run.

Common commands

Command	Purpose
/preset ui [stop|restart]	Open or manage the web editor
/preset list	List Presets
/preset use <id|none>	Select or disable a Preset
/preset preview [id]	Compile a Preset without sending a request
/preset validate [id]	Validate one Preset or all Presets
/preset diagnostics	Show runtime and extension diagnostics
/profile list	List and preflight profiles
/profile save <id> [--overwrite]	Capture the current runtime as a profile
/profile use <id>	Preflight and apply a profile once
/profile status	Show last-applied provenance and runtime drift
/payload next [save=<path>]	Inspect the next redacted provider payload

See the complete command reference.

Experimental foreground delegation

The optional @zihanw/pi-forge-subagents package provides foreground delegation on top of pi-forge's /subagent host port. The model can discover eligible profiles with forge_subagent_profiles and invoke one with forge_subagent; humans use /forge-agent plan and /forge-agent run.

This feature is experimental and profiles are not delegatable by default. Enable each profile in the trusted project's .pi/forge/subagents.json (or the optional package's read-only legacy fallback in .pi/forge/config.json.subagents). Interactive execution presents an immutable plan for approval unless the project explicitly authorizes unattended model invocation.

Security boundary: The current backends are shared-user processes, not operating-system sandboxes. “Read-only” describes the model-visible tool policy. The child retains the invoking user's OS read permissions, and readable content may be sent to the selected provider and retained in Pi's session data. Timeout and cancellation are best effort, and /tree cannot undo provider requests, billing, or external effects.

Read foreground delegation and its safety model before enabling it.

Documentation

Learn

• Getting started
• Migrating to 0.5
• Prompt-stack concepts
• Agent-profile concepts
• Web editor
• Prompt-stack patterns and examples
• Custom macros and slots
• Prompt and payload debugging

Reference

• Commands
• Stack schema and policy
• Macros and slots
• Configuration
• Public API policy
• Experimental subagent host port

Develop and design

• Development setup
• Architecture and development rules
• 0.5 architecture plan
• Release process
• Roadmap
• Architecture and design index

Chinese user documentation starts at docs/zh-CN/README.md.

License

MIT