A reproducible Pi coding agent setup packaged with Nix. The flake builds Pi, installs the project-owned agents and extensions, and bundles the Rust-based Bash permission analyzer used by the permission-gate extension.
- Nix with flakes enabled
- macOS Apple Silicon, macOS Intel, Linux ARM64, or Linux x86_64
Bun and jq are provided by the development shell; they do not need to be installed separately when using the flake commands.
Run the packaged agent directly (the configuration directory is required):
PI_CONFIG_DIR="$PWD/.pi" nix run .Pass arguments through to Pi after the installable and -- separator:
PI_CONFIG_DIR="$PWD/.pi" nix run . -- --helpEnter a development shell:
nix developBuild the default package:
nix buildRun all checks:
nix flake checkThe flake is pinned by flake.lock; update inputs intentionally with:
nix flake updateThe wrapper uses the immutable packaged Pi configuration from PI_CONFIG_DIR, which defaults to its /nix/store path. Packaged extensions and prompts are loaded directly from that path with --extension and --prompt-template; nothing is copied or linked into the user's Pi directory. That directory holds writable state only — credentials, settings, and sessions — and defaults to ~/.pi/agent. Override it with PI_AGENT_DIR when needed:
PI_AGENT_DIR="$PWD/.pi/agent" nix run .To use another immutable configuration source:
PI_CONFIG_DIR=/path/to/config nix run .Packaged agents are available as both Pi agents and prompts. The permission gate reads its default policy, and committing mode reads the change-describer agent, from PI_CONFIG_DIR; the subagent extension discovers packaged agent definitions there as well. Each falls back to the writable agent directory when PI_CONFIG_DIR is unset.
flake.nix— flake inputs and system output compositionnix/modules/— output-contributing modules for Pi, the analyzer, the development shell, and checkspkgs/pi/— pinned, offline Nix build of the upstream Pi coding agentagents/— project agents and promptspi/— project Pi extensions and their testspermissions.json— default permission policyllm/— session database and LLM integration toolspi/permission-gate/analyzer/— Rust-based shell command analyzerdocs/— design notes and configuration documentation
The top-level agents/, pi/, llm/, and permissions.json paths are the contents of the packaged end-to-end Pi configuration; they are intentionally not nested under a broader domain hierarchy.
The Pi wrapper puts the Rust analyzer on PATH, so the permission-gate extension resolves its default tree-sitter-bash-analyzer command at runtime. Set PI_PERMISSION_ANALYZER to override that command. Most TypeScript extension checks run through the Nix check named piExtensions; the permission gate is checked separately as permissionGate, and tree-sitter-bash-analyzer is also exposed as a package and build check.
To inspect the available flake outputs:
nix flake showDownstream flakes can build a Pi package with the shared Nix options. The option modules are merged with the packaged defaults, so individual Bash alternatives or extensions can be enabled without copying the full defaults:
pi.lib.${system}.mkPi {
modules = [
{
bashAlts.find.enable = true;
bashAlts.grep.enable = true;
extensions.kagi-search.enable = true;
extensions.cost-status.enable = false;
}
];
}Each bundled extension has an extensions.<name>.enable option. The bundled
names are permission-gate, propose-permission, elements, subagent,
committing-mode, cost-status, export-response, sesseract,
mac-system-theme, kagi-search, fetch-webpage, and response-pipe.
kagi-search and response-pipe default to disabled; the rest default to
enabled. Extensions can declare dependsOn as names or as { name, version }
records; version values are exact pins checked against the dependency's
extensions.<name>.version. Dependencies are included transitively even when
their own enable is false. propose-permission and response-pipe both
depend on permission-gate by default.
Defaults are available as lib.extensions (and lib.bashAlts for command
alternatives). extensionOpts remains as a backwards-compatible alias for
extensions; explicit bashAlts, extensions, and legacy extensionOpts
arguments are also available to consumers that do not use module definitions.
When fetch-webpage is enabled, the Pi wrapper provides curl and the extension
uses a short-lived curl subprocess for each tool invocation. It exits after
downloading the response; timeout or cancellation terminates it, and temporary
response files are removed.
Changes to packaged agents, extensions, permissions, or the analyzer are included automatically in the next Nix build. The Pi dependency itself is pinned in pkgs/pi/default.nix and should be updated together with its source and dependency hashes.