---
status: resolved
parent: "[[070-pi-ui-flex-spacer-pi-patch-task]]"
blocked-by: []
resolved-at: "2026-08-01T08:48:00-04:00"
tags:
  - ticket/research
---

# Community Pi packaging research

## Question

How do community Nix or dotfiles projects package patched Pi builds or local Pi extensions, and does that evidence change the planned `programs.pi-coding-agent.package = pkgs.pi-coding-agent.overrideAttrs ...` approach for the flex-spacer patch?

## Findings

Unauthenticated GitHub repository search found several Pi packaging and Pi dotfiles repositories, including `cyprx/pi.nix`, `peedrr/nix-pi-coding-agent`, `rrvsh/pi-coding-agent-nix`, `takinbo/pi-nix`, `tienedev/pi-mono-nix`, `ChauDucToan/pi-flake`, and Pi config/dotfiles repositories such as `devnos/pi-dotfiles` and `maolonglong/dot-pi-agent`.
The cloned survey set did not reveal a community project patching Pi internals for TUI layout.
Sources: `/tmp/pi-community-packaging/repos`; `/tmp/pi-community-packaging/repos/*` inspected below.

Nix packaging projects generally build or wrap Pi as a package rather than editing a live installed tree.
`rrvsh/pi-coding-agent-nix` packages Pi with `pkgs.buildNpmPackage`, fetches the upstream `earendil-works/pi` tag, builds the TypeScript workspaces, replaces workspace symlinks in `postInstall`, wraps `$out/bin/pi` with Nix `ripgrep` and `fd` on `PATH`, and runs a version install check.
Source: `/tmp/pi-community-packaging/repos/rrvsh__pi-coding-agent-nix/nix/pi-coding-agent.nix`.

`peedrr/nix-pi-coding-agent` similarly packages Pi from source with `buildNpmPackage`, fetches `earendil-works/pi`, seeds generated `pi-ai` model data from the published npm tarball, builds TypeScript workspaces, fixes workspace symlinks, and exposes a Nix wrapper module.
Its wrapper module sets `PI_PACKAGE_DIR`, `PI_CODING_AGENT_DIR`, optional resource path environment variables, and includes runtime packages such as `git`, `ripgrep`, `fd`, `gnutar`, and `unzip`.
Sources: `/tmp/pi-community-packaging/repos/peedrr__nix-pi-coding-agent/packages/pi/package.nix`; `/tmp/pi-community-packaging/repos/peedrr__nix-pi-coding-agent/wrapper-module.nix`; `/tmp/pi-community-packaging/repos/peedrr__nix-pi-coding-agent/flake.nix`.

`ChauDucToan/pi-flake` packages Pi from upstream source with Bun and provides Home Manager and NixOS modules.
Its module exposes a package option, then uses `cfg.package` in `home.packages` or `environment.systemPackages`; when extra environment is requested it wraps `cfg.package}/bin/pi` in a `symlinkJoin` wrapper.
It installs extension strings imperatively by running `pi install` during activation.
Sources: `/tmp/pi-community-packaging/repos/ChauDucToan__pi-flake/package-src.nix`; `/tmp/pi-community-packaging/repos/ChauDucToan__pi-flake/base-module.nix`; `/tmp/pi-community-packaging/repos/ChauDucToan__pi-flake/hm-module.nix`; `/tmp/pi-community-packaging/repos/ChauDucToan__pi-flake/module.nix`.

`takinbo/pi-nix` packages Pi from upstream source with `buildNpmPackage`, exports an overlay that provides `pi`, skips network model generation in `preBuild`, and wraps Node with the Pi CLI plus Nix runtime tools on `PATH`.
It is a full package/overlay pattern, not a live-tree patch pattern.
Source: `/tmp/pi-community-packaging/repos/takinbo__pi-nix/flake.nix`.

`tienedev/pi-mono-nix` packages a prebuilt Pi release tarball rather than source.
It wraps the prebuilt binary with runtime tools and environment settings, and on Linux adds library path support.
This pattern is convenient for distributing an unchanged binary but is a poor fit for our flex-spacer source patch because it provides no TypeScript source-level patch seam.
Source: `/tmp/pi-community-packaging/repos/tienedev__pi-mono-nix/package.nix`; `/tmp/pi-community-packaging/repos/tienedev__pi-mono-nix/README.md`.

`cyprx/pi.nix` has two relevant patterns.
It packages Pi from the published npm tarball in `nix/pi-coding-agent/default.nix`, using `buildNpmPackage`, a vendored lockfile, and a Node wrapper.
It also has `mk-pi.nix`, a composition wrapper that bakes extension derivations into `$out/share/pi-extensions`, dispatches selected extensions via `-e`, and wraps the underlying Pi package with extension runtime inputs.
This supports the idea that extensions and Pi runtime wrapping can be handled declaratively, but it is still a wrapper/composition pattern rather than patching TUI internals through an extension.
Sources: `/tmp/pi-community-packaging/repos/cyprx__pi.nix/nix/pi-coding-agent/default.nix`; `/tmp/pi-community-packaging/repos/cyprx__pi.nix/nix/lib/mk-pi.nix`; `/tmp/pi-community-packaging/repos/cyprx__pi.nix/nix/home-manager-module.nix`.

Pi dotfiles repositories usually deploy extension/config trees rather than patching Pi itself.
`maolonglong/dot-pi-agent` treats the repository as the live `~/.pi/agent` directory, registers `extensions/` and `themes/` through the `package.json` `pi` field, and documents that changes take effect on next Pi launch.
`devnos/pi-dotfiles` copies settings and extension files into `~/.pi/agent`, installs npm dependencies, and replays `pi install` for selected packages.
`abboskhonov/pi-dotfiles` tracks selected `.pi/agent` settings, models, themes, and extensions, while excluding auth, sessions, and binaries.
Sources: `/tmp/pi-community-packaging/repos/maolonglong__dot-pi-agent/README.md`; `/tmp/pi-community-packaging/repos/maolonglong__dot-pi-agent/AGENTS.md`; `/tmp/pi-community-packaging/repos/maolonglong__dot-pi-agent/package.json`; `/tmp/pi-community-packaging/repos/devnos__pi-dotfiles/README.md`; `/tmp/pi-community-packaging/repos/devnos__pi-dotfiles/install.sh`; `/tmp/pi-community-packaging/repos/abboskhonov__pi-dotfiles/README.md`.

The earlier community UI/layout survey remains relevant for the patch-vs-extension boundary.
`0x-rya/pi-local-mods` patches Pi internals for fixed-bottom layout behavior rather than packaging it as an extension, while UI extensions such as `pi-powerline-footer` stay within widget/footer/editor APIs.
This reinforces that the flex-spacer belongs in Pi internals/package patching, while the compact status belongs in an extension.
Sources: `/tmp/pi-existing-extension-survey/repos/0x-rya__pi-local-mods/README.md`; `/tmp/pi-existing-extension-survey/repos/0x-rya__pi-local-mods/scripts/apply.py`; `/tmp/pi-existing-extension-survey/repos/nicobailon__pi-powerline-footer/README.md`; `/tmp/pi-existing-extension-survey/repos/nicobailon__pi-powerline-footer/index.ts`.

No inspected community project showed an established pattern of overriding Home Manager's nixpkgs `programs.pi-coding-agent.package` specifically with `pkgs.pi-coding-agent.overrideAttrs` for a local source patch.
However, multiple community packages expose or use a package option / wrapper composition boundary, and nixpkgs itself exposes the same `programs.pi-coding-agent.package` option in this system as established by `[[072-pi-ui-patched-pi-packaging-research]]`.
The absence of an exact community example does not undermine the plan; it mostly means the plan is using the standard Nix package override seam rather than copying a community recipe.
Sources: `/tmp/pi-community-packaging/repos/ChauDucToan__pi-flake/base-module.nix`; `/tmp/pi-community-packaging/repos/cyprx__pi.nix/nix/home-manager-module.nix`; `[[072-pi-ui-patched-pi-packaging-research]]`.

## Answer

Community evidence supports, rather than changes, the planned packaging approach.
For a Pi internals change, use a Nix package-level source patch.
For extension/config deployment, use a managed extension/config tree or a package-composition wrapper.

The flex-spacer should remain a source-level patch to `pkgs.pi-coding-agent` assigned through Home Manager's `programs.pi-coding-agent.package` option.
This matches the community norm of treating Pi itself as a Nix package and avoids the fragile live-copy pattern.

The compact status extension should remain separate and dotfiles-managed as an extension.
Community config repositories frequently track or package extensions, and wrapper projects demonstrate declarative extension composition, but none of that makes the flex-spacer extension-only.

## Implications for implementation

Keep `[[070-pi-ui-flex-spacer-pi-patch-task]]` as a Pi package patch task.
Use `[[072-pi-ui-patched-pi-packaging-research]]` as the concrete packaging plan.
This follow-up adds confidence that community patterns do not point to a better wrapper-only or extension-only route.

If implementation wants to reduce rebuild cost or improve modularity later, `cyprx/pi.nix` and `peedrr/nix-pi-coding-agent` are useful references for extension composition and wrapper modules.
They do not replace the need for source patching the layout.

## Limitations

GitHub code search was not authenticated, so this research used repository search, cloned likely repositories, and local grep.
It is not exhaustive.

Some community packages target older Pi package names or versions and are useful for packaging shape, not exact current implementation details.

## Citations

- `/tmp/pi-community-packaging/repos/rrvsh__pi-coding-agent-nix/nix/pi-coding-agent.nix`.
- `/tmp/pi-community-packaging/repos/peedrr__nix-pi-coding-agent/packages/pi/package.nix`.
- `/tmp/pi-community-packaging/repos/peedrr__nix-pi-coding-agent/wrapper-module.nix`.
- `/tmp/pi-community-packaging/repos/peedrr__nix-pi-coding-agent/flake.nix`.
- `/tmp/pi-community-packaging/repos/ChauDucToan__pi-flake/package-src.nix`.
- `/tmp/pi-community-packaging/repos/ChauDucToan__pi-flake/base-module.nix`.
- `/tmp/pi-community-packaging/repos/ChauDucToan__pi-flake/hm-module.nix`.
- `/tmp/pi-community-packaging/repos/ChauDucToan__pi-flake/module.nix`.
- `/tmp/pi-community-packaging/repos/takinbo__pi-nix/flake.nix`.
- `/tmp/pi-community-packaging/repos/tienedev__pi-mono-nix/package.nix`.
- `/tmp/pi-community-packaging/repos/tienedev__pi-mono-nix/README.md`.
- `/tmp/pi-community-packaging/repos/cyprx__pi.nix/nix/pi-coding-agent/default.nix`.
- `/tmp/pi-community-packaging/repos/cyprx__pi.nix/nix/lib/mk-pi.nix`.
- `/tmp/pi-community-packaging/repos/cyprx__pi.nix/nix/home-manager-module.nix`.
- `/tmp/pi-community-packaging/repos/maolonglong__dot-pi-agent/README.md`.
- `/tmp/pi-community-packaging/repos/maolonglong__dot-pi-agent/AGENTS.md`.
- `/tmp/pi-community-packaging/repos/maolonglong__dot-pi-agent/package.json`.
- `/tmp/pi-community-packaging/repos/devnos__pi-dotfiles/README.md`.
- `/tmp/pi-community-packaging/repos/devnos__pi-dotfiles/install.sh`.
- `/tmp/pi-community-packaging/repos/abboskhonov__pi-dotfiles/README.md`.
- `/tmp/pi-existing-extension-survey/repos/0x-rya__pi-local-mods/README.md`.
- `/tmp/pi-existing-extension-survey/repos/0x-rya__pi-local-mods/scripts/apply.py`.
- `/tmp/pi-existing-extension-survey/repos/nicobailon__pi-powerline-footer/README.md`.
- `/tmp/pi-existing-extension-survey/repos/nicobailon__pi-powerline-footer/index.ts`.