Distribution and Licensing

Distribution and Licensing

What PiCode is

PiCode owns its editor tree. The editor is built from picode-source/ — PiCode's own source tree, versioned in the repository — by dev/build.sh, and the product layer is applied onto it before compiling. That is what makes the following true:

• product.json is applied from data before compiling, so product keys can be deleted, not only overridden;
• resources/app/extensions/ is the built-in extension scan path, so the connector ships as a built-in extension with no install step;
• a data/ folder beside the executable switches the build to portable mode;
• the file names are PiCode's: PiCode.exe, bin/picode*, and the Start Menu tile manifest — the brand assets (picode.ico, picode-icon.svg, picode.svg) live in the tree and are stamped by the build.

The layers

#	Layer	Artifact	Applied by
1	Editor	picode-source/, compiled by dev/build.sh	the build
2	Product delta	distribution/product-delta.json → picode-source/product.json	distribution/apply-product-delta.mjs, in phase 1 of the build
3	Portable profile	data/{user-data,extensions,tmp}	dev/stage-distribution.sh
4	Defaults	distribution/settings.json → data/user-data/User/settings.json	dev/stage-distribution.sh, only when absent
5	Agent runtime	pinned in distribution/runtime.json	dev/pi-runtime.sh

The staging step is dev/stage-distribution.sh [pack-dir] (default ./PiCode-Win32-x64). It is idempotent — a second run reports every step as already current. (A retired apply script that performed these actions against a pre-built archive was removed on 2026-09-29 and remains only in git history.)

The product delta

distribution/product-delta.json is the only source of PiCode's identity and version. It is data, applied by a Node program (distribution/apply-product-delta.mjs) with four sections: set, unset, unsetNested, unsetArrayEntries. Node rather than PowerShell because Windows PowerShell 5.1 caps ConvertTo-Json depth at 2 and escapes non-ASCII, which would corrupt a 77-key product carrying an 8 KB nested object.

The release workflow reads the version from set.version before tagging — there is no second place where the version could disagree with the product.

Two findings shaped it, and both came from running the build rather than reading the diff. They are the first thing to read before changing the delta:

1. A key that is iterated must be empty, not absent. The extension service calls .some() on builtInExtensionsEnabledWithAutoUpdates without a guard; deleting the key crashed --list-extensions with is not iterable.
2. A nested object that is dereferenced must be pruned, not deleted. defaultChatAgent is read without a guard in a startup path; deleting it produced a grey, blocked window with Cannot read properties of undefined (reading 'chatExtensionId'). Its fourteen endpoint keys are removed individually, which removes every api.github.com and aka.ms endpoint while keeping the shape.

Both states are valid JSON, which is why neither is visible in review.

The portable profile

data/ beside the executable: user data, extensions, tmp, the Pi profile. Two paths are easy to confuse, so both are stated: the user data directory is data/user-data, and the extensions directory is data/extensions.

The profile is disposable by design: deleting data/ yields a clean PiCode, and copying it moves the whole PiCode. Nothing is written outside it; the future cloud-sync unit is this folder as one piece.

The agent runtime

picode.pi.runtime selects which pi runs: path (the pi on PATH), managed (PiCode's own), or custom. The managed runtime's version is pinned in distribution/runtime.json and installed on demand by dev/pi-runtime.sh into the pack (resources/pi-runtime).

It is installed on demand, never shipped in the archive, and the measured numbers are the reason: the package's dist/ is 20 MB but is not self-contained, while a clean install is ~410 MB, most of it multi-platform @esbuild. It is invoked as node <bundle>/cli.js rather than through the npm .cmd shim, because Node cannot execute a .cmd without a shell since the CVE-2024-27980 hardening, and a shell would couple it to quoting rules for wherever the distribution was unpacked.

Updating VS Code

A newer VS Code is a merge against picode-source/, not a download: see Building PiCode. There is no archive to extract and no script to re-run — the tree is the source, and the identity is applied by the build.

The in-product updater is disabled by design (updateUrl is empty); releases ship via the static JSON feed produced by dev/update-feed.mjs — see CI and Releases.

Read the machine type of an archive before building on it. An ARM64 tree on an x64 machine fails at the OS loader before any PiCode code runs, with nothing in the repository to indicate why.

Verification

Machine-checkable, in the order that catches the most:

What	How
Branding	bin/picode.cmd --help prints PiCode — Agentic Code Editor <version> and a usage line reading picode.exe
Icons	the window and task bar show the PiCode mark, and the left bar shows media/picode.svg
Portable profile	the newest log directory is under data/user-data/logs/, and %APPDATA% is untouched
Connector activated	the picode connector's activation line in window1/exthost/exthost.log
Runtime in use	the PiCode output channel prints [pi] starting from <mode> runtime: <path>
No renderer errors	no Uncaught or TypeError with ELECTRON_ENABLE_LOGGING=1
Connector logic	npm test in extensions/picode: hermetic suites (runtime resolver, pi list parser, usage arithmetic, context block)
Protocol and CLI	live tests against a real pi on PATH

What is PiCode's name and what stays upstream's

Renamed by the build: PiCode.exe, bin/picode*, window title, About dialog, Start Menu tile manifest, the executable icon.

Still legitimately upstream's, and staying so:

• the VS Code lineage in the licence files and the built bundle, where "VS Code" must keep appearing because it is the upstream base — documentation saying otherwise would simply be false;
• OS-level identity of an installed editor (installer, Start Menu entry, Add/Remove Programs, protocol handlers, registry keys) — PiCode ships portable; installer-style identity would be a separate decision.

Licensing

• PiCode itself: MIT — Copyright (c) 2026 Tomás Platero (LICENSE).
• Upstreams, all MIT, all preserved: VS Code (microsoft/vscode), Pi (earendil-works/pi), Gentle AI and Engram (Gentleman-Programming).
• PiCode is not an official distribution of VS Code, Pi or Gentle AI.
• The editor installs extensions from Open VSX: the Microsoft Marketplace terms do not license third-party builds to use their gallery. Marketplace-only themes are therefore uninstallable here, and the UI says so.

The business model, in one paragraph

The program stays free and complete — no trimmed features, no server dependency. What is sold, later, is cloud sync of the profile: data/ (PiCode settings + Pi profile + Gentle AI state) uploaded and downloaded as one unit. Credentials will require explicit consent and encryption before leaving the machine. Nothing in the distribution strategy depends on withholding functionality.

---

Related: Getting PiCode · Building PiCode · CI and Releases