PiNova is a Nix-packaged Pi distribution. The repository contains the Pi source in pi/ and distribution packaging outside that directory. The foundation does not bundle extensions or add runtime features.

Source layout #

pi/: the imported Pi source tree and its preserved upstream history.
nix/: the package, development shell, and pinned model metadata input.
scripts/: development preparation and installed-package validation.
upstream.json: the exact Pi source baseline and relocation commit.

The source baseline is upstream main at bd3c9b823762b7383954aa49e13ee350471015fe, cloned from https://github.com/earendil-works/pi. The first fork commit moves the tracked source into pi/ without changing file contents or permissions. Upstream packages report version 1.3.0; this baseline includes commits after that release. upstream.json records the immutable source revision.

Repository #

The repository uses Git-backed jj. The local integration bookmark is main. The upstream remote points to original Pi. The origin remote is git@tangled.org:did:plc:gpnrmpjtsa3wcun4fcpv4fnn, the exact address supplied for this fork. Remote access and publication are not established by local configuration.

Preserve upstream ancestry when incorporating selected updates. The directory relocation is a separate commit so its effect remains inspectable. The full reachable history must be reviewed before public publication; a local clone is not a publication.

License #

Pi source retains its upstream MIT license at pi/LICENSE. Distribution packaging uses the MIT license at the root.

Commands #

From the distribution root:

nix develop -c node scripts/dev-setup.mjs
nix develop -c node scripts/dev-check.mjs
nix develop -c node scripts/dev-run.mjs --offline --version
nix build -L .#pi-nova
nix flake check -L

The development setup prepares a disposable source copy under .state/dev/pi. It installs locked dependencies with lifecycle scripts disabled and hydrates pinned model metadata there. Development checks do not write formatting or generated files into the tracked pi/ tree. Re-run setup after source changes. The development shell itself does not install dependencies or change user configuration.

The package exposes pi-nova, without replacing an existing pi command. Package validation runs an offline source build, upstream format/type/dependency checks, selected credential-free tests, and installed CLI/RPC smoke checks. It does not run the full provider test suite or make inference calls.

--offline disables automatic model/update networking. It does not block network access from explicit inference requests or tools. Use disposable HOME/configuration state for tests; offline mode is not a sandbox.

Platforms and scope #

The flake declares x86_64 and aarch64 Linux and macOS outputs. The foundation is validated on this x86_64 Linux desktop. Other outputs are declared build targets, not claimed passing builds. Optional native dependency lifecycle scripts remain disabled. Actual graphical clipboard behavior and other-platform native helpers require separate validation.

This repository does not contain private edition extensions, migrate settings, install a service, or activate Home Manager. Source integration, remote publication, installation, and activation are separate operations.

State #

The installed and development launchers default to $HOME/.pinova/agent. An explicit PI_CODING_AGENT_DIR is honored. This is separate from upstream Pi's .pi state and the earlier fork's .pi-nova state. No settings or sessions are copied between them.

Development setup refuses to overwrite an existing .state/dev directory. Remove that disposable directory deliberately before recreating it after source changes. Do not remove user configuration or session directories as part of development preparation.

Build inputs #

Nixpkgs is pinned in flake.lock. npm dependencies use Pi's unchanged package-lock.json and a fixed-output cache hash. The typed model catalog is pinned by immutable URL revision and SHA-256 in nix/model-data.nix. The original upstream catalog pin lacks a model referenced by this source revision's tests. The distribution pins a newer verified catalog without changing Pi's source or its original pin file. The unchanged upstream hydrator creates provider data in the build or disposable development copy. Ordinary builds do not fetch a mutable catalog.