Pictto

Pictto is a Pi extension for exploring product and design ideas in a local browser workspace. The active Pi agent does the reasoning while the browser presents parallel branches, rich visual questions, follow-up rounds, and final design review.

How it works

1. Run /pictto <idea> in Pi.
2. The current Pi agent creates two to four parallel exploration branches.
3. Pictto opens a loopback-only browser workspace. Under WSL, it uses the Windows default browser rather than a Linux browser inside the distribution.
4. Each round shows every question together. Answer them in any order, or explicitly skip a question.
5. The browser sends one batch only after the entire visible round is resolved.
6. The Pi agent reasons over that batch, opens follow-up rounds when useful, and completes each branch with a finding.
7. The final proposal appears in the browser for Approve, Revise, or Cancel review.

Pictto does not run another agent runtime. It uses the model, context, tools, and session that are already active in Pi.

Install

Install as a Pi package from a local checkout:

pi install /absolute/path/to/pictto

For a quick development load after building:

vp install
vp pack
pi -e ./dist/index.js

The package manifest exposes dist/index.js through pi.extensions. Pi core packages are peers supplied by the host; ws is the only runtime dependency.

Use

/pictto Design a calm budgeting app for freelancers

The command sends a real user message into the current Pi workflow. The agent can then call:

• pictto_round: start a board, open a complete question round, complete a branch, or inspect the latest snapshot.
• pictto_review: present the synthesized proposal and wait for approve, revise, or cancel feedback.

The browser renderer registry supports selection, multi-selection, confirmation, ranking, rating, text, code, image and file input, diffs, plans, option comparisons, section review, thumbs, emoji reactions, and sliders. These remain one consolidated browser boundary rather than separate Pi tools.

Round semantics

A visible round is atomic from Pi's perspective:

• All questions in the current round render at once.
• Answers may be entered in any order.
• Every question needs an answer or an explicit skip.
• The submit button remains disabled until the round is complete.
• Pi receives one round_submit batch, never partial per-widget messages.

A revision decision reopens exploration branches so the agent can ask follow-up rounds before presenting another review.

Recovery and lifecycle

Every Pictto tool result stores the latest board snapshot in details.board. On session start or tree navigation, the extension restores the latest Pictto snapshot from tool results on the current branch. This keeps recovery aligned with Pi's branch semantics without a separate state database.

The HTTP and WebSocket bridge starts lazily when a command-driven tool needs it. It binds only to 127.0.0.1 on an ephemeral port, validates Host and WebSocket Origin, sends a full snapshot on reconnect, and shuts down forcefully and idempotently with the Pi session.

Development

vp install
vp run check
vp pack
npm pack --dry-run

Tests cover domain transitions and failures, real HTTP and WebSocket behavior, reconnect snapshots, complete round and review exchange, security rejection, cancellation and shutdown, extension registration and workflow behavior, and browser batch and renderer invariants.

See ARCHITECTURE.md for the runtime design and CODE_STYLE.md for project conventions.