Technical reference

Requirements: Node.js 22.19 or newer, npm, and Git. SpecPi uses Pi 0.84.4 or newer. If Pi is missing, the confirmed install adds the reviewed pinned Pi package. Uninstalling SpecPi leaves that package installed.

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

npm install --global specpi@0.19.1

git clone --branch v0.19.1 --depth 1 https://github.com/TannerMidd/SpecPi.git
cd SpecPi
./specpi plan
./specpi install
./specpi doctor

git clone --branch v0.19.1 --depth 1 https://github.com/TannerMidd/SpecPi.git
cd SpecPi
.\specpi.cmd plan
.\specpi.cmd install
.\specpi.cmd doctor

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

Native Pi package mode is limited. pi install npm:specpi loads extensions, skills, and themes, but does not run the managed installer or provide its browser runtime, supporting packages, instructions, shell integration, backups, or ownership records.

1. 1

   Restart Pi. Restart so Pi loads SpecPi's extensions, skills, theme, and managed settings.

2. 2

   Enter focused mode in the terminal. Run /spec to switch to the focused execution surface. Run it again to leave. Chat manages its own display.

3. 3

   Choose collection. The wishlist asks once whether capability-gap collection is enabled. Reports are local, sanitized, bounded, and deduplicated by task.

No automatic implementation. Evidence can qualify an item, but only a selection in /harness-improvement authorizes a change.

Recurring capability gaps enter the review menu. A person selects one item. Repository checks and capability validators determine whether the item can retire. A failed gate leaves it selected. Later evidence returns it as review-needed.

SpecPi keeps implementation in one accountable working context. Scope, experiment, and challenge controls make path expectations and review evidence visible.

Optional task cards, verification receipts, and human outcome feedback make the boundaries and evidence of a change easier to review.

Use an optional task card when a shared contract would improve continuity. It records the objective, fixed requirement IDs, acceptance checks, expected paths, hypothesis, rollback, and non-goals on the current session branch.

Verification receipts

Improvement verification records actual gate results and fingerprints supported source and validation inputs. A changed source snapshot invalidates the evidence. Receipts retain hashes and runtime metadata, separately from model explanations; they retain neither source contents nor raw command output. A receipt describes what was checked and is not independent proof that the change meets its acceptance checks.

Outcome feedback

With collection enabled, /wishlist outcome <gap-id> records a human assessment of the latest local retirement with a receipt: helped, failed, not exercised, or reverted. Corrections preserve history. Negative feedback can surface a review need; it never authorizes implementation or performs a revert. Older retirements without receipts remain unassessed.

In the terminal, choose a mode at session start. In RPC/Chat, Guard starts without a blocking startup selector; use /guard after connecting to choose a mode. Approvals apply to one exact call and one session. Only a structurally proven critical mutation locks the session. Parser uncertainty and invalid cleanup syntax are denied without locking later work.

Use /guard to inspect or change the mode. Available actions include status, guard, strict, off, unlock, and clear-approvals.

/files opens the project browser for source, rendered Markdown, Git diffs, and bounded review comments.

Browser QA

Browser tools open a fresh isolated Chromium context. Load the page, inspect rendered structure, test interactions, resize across desktop, tablet, and mobile viewports, then capture bounded evidence. Source inspection does not verify rendered appearance.

Use browser_diagnostics for active-page JavaScript exceptions, console errors, failed requests, and HTTP errors. Output is bounded and best-effort sanitized, not guaranteed secret-free. Empty results do not prove application health. Close discards the buffer; explicit clear discards all retained records, including filtered or unreturned ones.

browser_press exercises keys and chords; browser_select_option selects native dropdown options by value, label, or index; browser_wait_for waits for an element state, exact text, or exact URL. These tools default to a five-second deadline (maximum thirty seconds). Refresh snapshot refs after mutations or navigation.

Isolation boundary. The browser does not attach to a personal Chrome profile, cookies, passwords, or extensions. It runs as a separate process and does not provide operating-system isolation.

The task and evidence reference covers task cards, handoff packets, and outcome feedback.

The installer merges documented settings paths and preserves unrelated configuration. SpecPi manages global instructions and shell integration only inside marked blocks. Plan output is non-mutating. Install, update, and uninstall require confirmation unless --yes is supplied.

Pi extensions run with user permissions. Use OS permissions, a least-privilege account, a container, or a VM for hostile code or data. Read the security model ↗.

npm install --ignore-scripts --omit=peer --no-package-lock
npm run format
npm run check
npm run setup:browser
npm run test:browser
npm run test:site:browser
npm --prefix vscode run test:render
npm --prefix vscode run test:vsix

JavaScript and TypeScript use four-space indentation, explicit braced control flow, and one statement per line. The repository check validates formatting and syntax, strictly type-checks the browser extension, runs the Node test suite, and executes registry-linked validators with isolated prerequisites. Browser tests use repository-local Chromium and cover the public pages at desktop, tablet, and mobile sizes. Required CI browser commands reject skipped coverage; Pages deployment waits for the same rendered check. No visual baseline is automatically created.

On by default at Pi startup, after compatibility and Guard checks. Up to two read-only Pi workers can assist while the parent owns edits and checks their findings. Startup launches no workers.

Start Pi normally after installing SpecPi. Then use:

/delegate status
/delegate limits
/delegate cancel <batchId>
/delegate off

Use /delegate on to re-enable after turning it off or a safety revocation. Off and revocations survive reloads and session switches; restarting Pi reapplies the on default.

The worker panel shows progress; expand tool results to read findings and evidence. Workers receive only assigned context and can read selected snapshots. They have no shell, writes, live web access, or nested delegation.

Use /delegate limits for the effective call and byte allowances. While delegation is off, /delegate budget configures their multiplier and /delegate timeout 15 saves a timeout of 1–60 whole minutes; /delegate timeout reset restores 10. Batch timeouts are twice the job timeout; queue and follow-up time count from admission. Toggling, reloading or changing settings does not reset spent counters. These limits do not cap provider charges. Restart Pi after updating SpecPi.

Before delegating: selected context goes to the configured provider. Workers do not inherit every parent hook or provider setting; unsupported configurations can block activation. Review the compatibility and privacy boundaries.

See why we chose this design and the tool protocol. Quality, speed, and cost gains remain unmeasured.

Chat 0.4.1 is a separately installed preview. Install VS Code 1.96+, external Node.js 22.19+, and Pi 0.84.4+ on the workspace extension host; SpecPi is optional. Configure your provider in Pi first, then open a trusted filesystem workspace. SSH, WSL, and containers use the remote workspace host; browser-only and virtual workspaces are unsupported.

Install SpecPi Chat from Marketplace, or build a VSIX from the repository checkout used for the source installation above:

npm --prefix vscode run package
code --install-extension .specpi-test/vscode/specpi-chat-0.4.1.vsix

You can also use Extensions: Install from VSIX…. Open SpecPi in the Activity Bar and choose Connect Pi. Opening the sidebar alone does not launch Pi. If discovery fails, application-level specpi.chat.piPath and specpi.chat.nodePath accept executable paths, not shell commands.

Separate installations. The npm package does not contain or install Chat. Installing a VSIX does not update the harness. Older Guard installations may take about 30 seconds to finish startup; Chat waits up to 90 seconds and never approves early dialogs. Update SpecPi and reconnect to obtain the RPC startup and report-dialog fixes. No Marketplace publication is implied.

Explicit context and privacy

Attach UTF-8 workspace files/selections, use @ file suggestions, or click validated code references. Select PNG, JPEG, GIF, or WebP images, paste screenshots, or drop image files. Images may be explicitly selected outside the workspace; text context stays inside it. Review attachments before sending. Pi owns authentication, tools, and provider requests.

Up to eight mixed attachments: text is limited to 64 KiB each; images to 5 MiB each and 20 MiB per prompt, 16,384 pixels per side and 40 million pixels. An image-capable model is required. Media display is bounded and remote images are not fetched by the webview. Sent images persist in extension-owned Pi conversations. Filename/format checks are not a secret detector.

Independent conversations and controls

Search history, rename, or archive/restore conversations without deleting their files. Switching chats or folders preserves background processes, drafts, attachments, queues, usage, scroll position, and approvals. Open a conversation marked Needs input to respond; switching never grants approval. Stop and Disconnect target the selected chat.

Click Restart Pi in the Chat title bar or run SpecPi: Restart Pi from the Command Palette to reload the selected chat's Pi extensions and resume its saved conversation. Restart interrupts active responses and clears queued sends and pending approvals; unsent drafts and attachments remain available, and other conversations keep running.

Use /model or the model selector, choose supported thinking levels including max, and inspect Pi-reported cost/context usage even during active responses. Search displayed messages, copy/export visible Markdown, or open native working-tree/staged diffs. Branching and editing an earlier prompt preserve the source conversation and restore a draft without sending it or rolling back workspace files.

Shared files, separate processes. Concurrent chats are not isolated worktrees. Keep one writer per working directory for overlapping changes. Use separate workspaces/worktrees for parallel writers. Closing the extension host stops all its Pi processes; provider availability, billing, and image support remain upstream concerns.

For exact limits, queue recovery, startup troubleshooting, and local/native tests, see the extension guide. TUI-only /spec and /files interfaces remain terminal controls; Chat uses its own display and native Git review.

Ask Pi to run a dev server, long test suite, or watch build in the background. These are model tools, not slash commands. Starting a process is not proof that a service is ready.

Starts require interactive approval, including with Guard off; headless starts are denied. Approval is for the exact execution in this session, with no allow-once option. Guard denials and locks still apply. At most four active or cleanup-unconfirmed tasks are allowed, with 32 completed records, 256 KiB of output per task, and 64 KiB raw-output reads. Log cursors count UTF-8 bytes including stdout/stderr markers, before terminal-control escaping.

Commands use /bin/sh on POSIX or system cmd.exe /d /s /c on Windows, not Pi's configured Bash. They inherit the process environment except NODE_OPTIONS and NODE_PATH. No PTY or interactive stdin is provided.

Best-effort cleanup, not a sandbox. Stop tasks when finished. Deadlines, session replacement, reload, tree navigation, and shutdown initiate cleanup, but escaped descendants may survive. If cleanup is unconfirmed, retry background_stop for the listed IDs, then /reload after cleanup confirms. IDs do not survive runtime replacement; inspect remaining processes manually. Output is memory-only in the extension, but returned text may enter conversation/provider retention. Read the security boundary.