Your Pi setup.
A smaller base.

Getting started

Install Node.js 22.19+, Git, npm, and Pi on PATH. Connect a provider in terminal Pi and confirm it works before installing SpecPi. The complete base is tested with Pi 1.0.0.

npm install --global specpi@latest
specpi plan
specpi install
specpi doctor

Review the plan, confirm, then restart Pi. Your provider, model, and unrelated settings are preserved. Install, update, and uninstall require confirmation; --yes supplies it for automation.

For a source checkout, use node scripts/specpi.mjs in place of specpi. PI_CODING_AGENT_DIR selects an alternate destination and SPECPI_PI selects a Pi CLI path.

specpi install --skip-package-install installs only scope and the improvement loop on a fresh profile. A plain pi install npm:specpi loads those packaged resources but does not set up the full base. Avoid installing the same resources both ways.

Default packages

Normal installs and updates install the seven pinned packages through Pi. SpecPi saves exact npm versions and checks the installed versions before completing the update. Each package keeps its own commands and configuration; existing resource filters are preserved.

specpi-browser-qa@0.3.0 provides 14 interaction, accessibility, diagnostic, and visual QA tools, not general-browser feature parity. Confirmed install/update invokes its installed Node bin to download Chromium and verify readiness. No Bun or OS libraries are installed. --skip-browser-install skips setup but still installs packages; --skip-package-install skips both. specpi doctor checks offline rendering, pixel comparison, and accessibility without downloading anything. If setup fails, install missing OS libraries manually and retry specpi install (or specpi update for an existing installation).

BetterWright remains an optional manual install with its own setup guide. Updates remove only unchanged SpecPi-added entries, restore pre-existing entries, and preserve user edits and downloaded tools. No personal browser, profile, cookie, or private Pi data is migrated. Package/browser-cache bytes can survive failed installs and uninstall; managed configuration rolls back on failure. Restart Pi and Chat connections after updating. Pi Goal X declares compatibility with Pi ≥0.83.0 and <2.0.0.

Optional tool groups ship hidden so their schemas stay out of every request until needed: /webaccess on offers the web search, check, fetch, and content tools for the session, /browser on offers Browser QA's fourteen tools, and /delegate on offers delegation. Each supports startup on to save the preference; off withdraws the group again. The agent can also ask for web access or Browser QA when a task needs one, which prompts you to allow it for the session; declining leaves the session unchanged, and it cannot offer itself a group without you. Delegation is not requestable that way. If a prompt becomes routine, /capability allow browser grants that group without asking again and /capability ask browser restores the prompt; /capability shows both states. A grant still announces itself when it fires and never applies to a headless session, and the agent is not offered the request in a headless one. The gap report tool is offered while local collection is on, or undecided in an interactive session so its first report can ask you; /wishlist on and /wishlist off switch collection and the tool with it. The authoring tools appear only during a /harness-improvement selection.

Long commands can run as background jobs, so a long eval or build does not hold the conversation. The agent starts one with the background tool, which returns at once; when the job ends, its exit code and last lines of output arrive as a message and the agent picks it up. /jobs lists them, /jobs output <id> shows recent output, and /jobs stop <id|all> stops them. Your permission rules for bash apply to every job, jobs end with the session, and the tool is offered only in interactive sessions. When the LANCET command guard is on, it checks each job's command the same way it checks bash.

Provider credentials, service configuration, and permission policies follow the upstream documentation. Installing a package does not complete its external service setup.

Scope

Use /scope set to declare project-relative files and directories, one per line. Review drift with /scope status.

Interactive writes and edits outside scope ask first. In headless mode they are recorded as pending. Shell commands and other tools are checked afterward against bounded Git snapshots.

Scope monitors drift; it does not sandbox tools. A tool may already have changed files before drift is reported. State follows the current Pi session branch.

The harness improvement loop

Start with an observed problem. You choose the change, define what success means, and verify it before closing the item.

1. Enable local observations with /wishlist on. Collection starts off; /wishlist off stops it. The gap-reporting tool stays visible either way and refuses to record until collection is on.
2. Review recurring gaps with /wishlist and select one through /harness-improvement in a complete SpecPi source checkout.
3. Follow the specpi-improve skill: record a bounded contract, make the smallest sufficient change, and gather direct acceptance evidence.
4. finish_harness_improvement checks the contract, source changes, repository checks, and registered validators before retirement.
5. Review the record with /wishlist history <gap-id>. Use /wishlist outcome <gap-id> to record your assessment.

An observation never authorizes a change. A regression returns the item for human selection. Records stay local, use sanitized summaries and salted identifiers, and are never uploaded automatically. Pi still sends model requests to your selected provider.

SpecPi Chat for VS Code

Download Chat 0.19.0, then run Extensions: Install from VSIX… in VS Code. Open a trusted project, select SpecPi in the Activity Bar, and choose Connect Pi.

Requires VS Code 1.96+ and Pi on the workspace host. Install SpecPi separately. On SSH, WSL, or containers, Pi and the extension must be installed on that host.

Chat supports the new base's commands, tool output, subagent activity and result cards, goal messages, usage reports, and approval dialogs. Provider sign-in, package-specific terminal settings, and custom footers remain in terminal Pi.

The Permissions button opens editable global or project settings. Saves require confirmation and keep a backup; restart Pi to apply them to this chat. Approval dialogs send your explicit choice back to Pi. Cancellation never grants approval.

Full Chat guide · Build and test Chat

Update and remove

npm install --global specpi@latest
specpi plan
specpi update
specpi doctor

Updates retire recorded old resources, restore legacy settings that still match ownership records, remove the shell marker block, and install the new package base. Modified retired files and old runtime directories are preserved under <agent-dir>/specpi/backups/.

Normal updates remove unchanged pi-lens entries originally added by SpecPi; pre-existing or user-modified entries and downloaded files remain. Restart Pi and Chat connections to unload old extensions. Unrelated settings and local improvement evidence remain intact. Modified retained resources require update --force; review the plan before using it. update --skip-package-install preserves the existing base without invoking its installer.

Run specpi uninstall to remove managed resources and restore package entries that still match SpecPi's recorded changes. Subsequent user edits, downloaded packages, caches, and private evidence remain on disk.

A failed install restores SpecPi-managed files and configuration. Upstream downloads and install-script effects cannot be rolled back.

Development

npm install --ignore-scripts --omit=peer --no-package-lock
npm run check
npm run check:pi-package
npm run check:base
npm run check:site

Use disposable Pi state for installer tests. check:base installs the real six-package base in isolation and checks loading, Chat RPC, explicit permission replies, updates, removal, and real offline Chromium QA readiness. It does not send model requests.

Website checks use the pinned Playwright browser; install it with npx --no-install playwright install chromium. Read the repository guide, security model, and release procedure before contributing.