Workbench

Talk to Workbench about what you want to improve.

Describe a problem, a recurring task or an idea. You do not need to learn a command or decide whether you need a native prompt template, a Skill, a System-Prompt Append or an Extension first. Workbench helps you work that out and develop a suitable solution.

Start with a conversation

Once Workbench is loaded in Pi, you can start with something like this.

Hello Workbench. I want to improve how I work with Pi.

Workbench, I keep doing this task by hand. Help me turn it into a useful Skill.

Workbench, go through these documents with me. I want to resolve the open decisions.

Use your own language and bring what you already know. If you have a concrete task, start there. You do not need a complete design or a prepared questionnaire.

Workbench is a critical collaborator. It helps examine assumptions, compare existing capabilities and reach a reasoned solution. Sometimes an existing feature or a short answer is enough, without creating any files.

What you can do with Workbench

• Improve how you work. Define the actual problem, inspect current sources and identify a change that would help.
• Develop prompts and Skills. Create, review or revise System-Prompt Appends, native Markdown slashprompts with arguments, Skills and project-specific Pi instructions at their responsible originals, within the agreed scope. Simple explicit reusable prompts use native prompt templates; richer reference workflows use Skills, and executable integrations use Extensions.
• Resolve decisions from documents. Work through material gaps and contradictions one question at a time, keeping one concise decision record.
• Find and use existing solutions. Assess Skills, Extensions and packages for their fit and requirements. Commissioned installation, configuration, updates and removal use Pi's native mechanisms.
• Prepare a technical project. For a new Extension or executable code changes, Workbench prepares a usable handoff. The receiving agent owns detailed planning, implementation and tests.

The result should be something you can use: a clear recommendation, a revised Skill, a traceable set of decisions or a concrete project handoff. It identifies what was actually done and checked, and what remains open.

Skill examples for your own work

Ask Workbench about the included templates, or have one adapted to your task.

These eleven templates are complete, adaptable Skill examples, not native prompt templates or already-installed user Skills. Offering a template does not install or activate it. Your personal Skills remain your originals and are not copied into the Workbench package. All eleven examples are listed in the template overview. The adaptation guide explains how the nine directory-based templates use your actual capabilities and only ask for material missing decisions.

Load Workbench in Pi

Workbench is a standalone native Pi Extension requiring Node.js 22.19.0 or later and a suitable Pi installation. Its core functions use Pi's native SDK and file tools; they require no personal settings, custom Skills or companion Extensions. Template-specific integrations such as Herdr and Intercom are optional.

GitHub releases and npm publication are separate. The 0.3.0 GitHub release provides the source and package archive; the maintainer publishes npm separately. The following command installs the version currently published on npm, not necessarily the latest GitHub release.

pi install npm:pi-blitz-workbench

For a single local Pi invocation from this project directory, you can load the Extension without a persistent package declaration.

pi --extension ./extensions/index.ts

Then address Workbench directly. Pi and your model select the native workbench tool; there is no fixed greeting parser. If your model does not pick up the entry, /workbench explicitly starts the same collaboration. You can include a task, such as /workbench Help me simplify this Skill.

Loading only registers the available capabilities. It does not start a conversation, create Workbench data, build the index or clean archives. An actual Workbench invocation starts that background work. Pi retains control over tool selection and restrictions.

Small supporting tools

Local reload and continuation

workbench_reload({}) requests a full native Pi resource reload without requesting another model turn. Pi may install missing or mismatched configured packages and update temporary package sources; not every reload does so. A reload request alone does not authorize installation or updates. Before invoking either reload entry, ensure the actual grant covers relevant possible package effects; otherwise stop and clarify the missing permission. Explicitly commissioned native package installs and updates remain allowed. Workbench adds no installer, reload replacement or technical permission enforcer. Reload alone does not start Workbench collaboration, build the documentation index or clean archives. The tool records the request and returns terminate: true. Pi skips the automatic follow-up only when every tool result in that batch terminates; mixed batches continue normally without forcibly aborting sibling tools. Workbench dispatches the reload command from native agent_settled, after the run finishes.

With workbench_reload({ initPrompt: "Continue the authorized task" }), the replacement extension runtime sends the prompt unchanged after all session_start handlers finish. The continuation identifies itself as model-origin content and asks the model to re-read the relevant currently offered Skills and their references. It grants no new authority and cannot guarantee that the model follows the request. Slash commands and templates inside the prompt remain literal text.

You can also use /workbench-reload, or /workbench-reload {"initPrompt":"Continue the authorized task"}. Input must be an object with no extra fields; a supplied prompt must be a non-empty, non-whitespace string. The tool reports only that reload was requested, not that it succeeded. Overlapping outstanding requests are rejected. A pre-aborted call queues nothing; aborting a run after a successful request does not revoke it.

The continuation starts from Pi's resources_discover hook, after session-start initialization but potentially before other discovery or UI work finishes. The continuation is branch-local and consumed before sending; a send failure can lose it without retry. A consumed prompt does not replay on ordinary later reloads, but navigating or forking to earlier branch state can expose it again. If reload fails after saving an unconsumed prompt, a later ordinary reload can still pick it up; a no-prompt Workbench reload or a non-reload session start discards it. This is not an exactly-once delivery guarantee. Reload does not make unsupported context files such as .pi/Pi.md load automatically. Project instructions belong in a verified native context source, normally AGENTS.md; existing supported guidance stays at its responsible original.

PiQuickDoku

PiQuickDoku searches the documentation shipped with your installed Pi version. Hits include full file paths, explicitly 1-based source lines and text excerpts. Broad results are bounded and omissions are disclosed. Read the original location with its surrounding context when needed.

The SQLite FTS5 index builds in the background on the first Workbench start and after an installed Pi-version change. An unchanged host version reuses the index. Neither conversation nor early queries wait for construction. If the index is not ready or reports an error, the LLM researches directly from available sources. A query alone never starts construction.

Archive originals

Before changing existing Pi-owned originals in the Pi agent directory, including Append, Skills and settings, Workbench requires a successful unchanged-original backup unless the resolved file belongs to a Git repository. Symlinks are classified by their targets. Repository-backed Skills, Extension projects and files outside the Pi directory require no Workbench backup. Repository membership does not imply that a file is committed or remotely backed up.

workbench_archive_original creates a gzip archive for an eligible original and returns status: "archived". Excluded files return status: "skipped" with a reason and create no archive. A missing or failed required backup stops the in-scope edit; a skipped backup grants no edit permission. A genuinely new file has no prior state to archive.

This is an instructed workflow, not a universal write barrier over every file tool. The authoring guide describes the archive format and its limits.

Retention and data

An actual Workbench start automatically cleans expired own archives in the background. Retention defaults to 30 days and can be changed through workbench_set_backup_retention under a matching task grant. Changing a setting alone deletes nothing.

Startup cleanup has no extra confirmation prompt. A native notice reports the effective retention and actual number of removed archives, including zero, or a concrete error. UI-less modes have no visible notice. A cleanup error does not prevent conversation startup; already completed deletions are not rolled back. Unknown formats, foreign files and symlink targets are preserved.

Settings, index and archives live outside the package under <Pi-agent-directory>/workbench/. Package updates do not replace them. Shutdown, reload and session replacement cooperatively abort and await retention; an active index worker is terminated and its exit awaited. The full retention contract covers the details.

Guides and sources

Workbench includes the following internal procedures. You do not need to study them to start a conversation. The LLM reads the relevant branch when needed.

• Shared Workbench workflow
• Grill with Docs
• System-Prompts, native prompt templates and shared editing rules
• Skill Authoring
• Extensions and project preparation
• Native Pi packages
• Curated starting points and their review limits

For agent instructions, Workbench uses Matt Pocock's Writing for Agents as its primary writing method. The complete, unchanged original ships with Skill Mechanics, provenance and its MIT license. No separate Skill installation is required. Human-prose writing Skills are optional; Workbench can write directly without them. Pi retains ownership of discovery, invocation, packages and runtime.

License and technical documentation

Workbench is MIT licensed. Bundled third-party references retain their own license and attribution notices. The documentation index links the working guides; the technical overview describes entries, helpers and storage. The Security Policy explains trust boundaries and reporting. Changes are recorded in the changelog.

Limits and local functional checks

A recommendation or template offer does not itself install, activate or publish anything. Workbench has no separate package manager, updater or permanent conversation mode. Actual changes follow the commissioned scope.

Functional tests are local development aids and ship in neither the public repository nor the npm package. Previously documented isolated Pi 1.5.0 SDK checks covered registration, reload ordering and continuation, strict inputs, abort and mixed-batch behavior, settings, retention and local documentation search. Provider responses were an offline test double; no personal context, Skills or companion Extensions loaded. Earlier typechecks passed with local Pi 1.3.0 dependencies and separately with installed Pi 1.5.0 declarations. The current local development dependency resolves to Pi 1.3.0; native host peers remain *. Node.js 22.19.0 is the declared minimum, not verified minimum-runtime support. Pi 1.5.0 is a reviewed source/evidence version, not a claim about the latest release. These checks do not prove real-model compliance or a complete visible user workflow.

Visible smoke tests on 8 November 2026 used Pi 1.5.0 with only Workbench loaded as an Extension, retaining normal user model configuration, Skills and prompts. The /workbench entry, native workbench({}) tool, local PiQuickDoku search and reading a reported original section succeeded with a live model. Retention reported zero removed archives. No installation, updates, reload or original/settings edits were performed. This verifies those observed entry/search flows, not configuration-free operation, archive deletion, reload recovery, general model compliance or minimum-Node support.