pi.nix

A Nix flake for pi, the terminal coding agent.

It provides:

• packages for nix run / nix build
• a default npm-built package and an optional Bun-built variant
• NixOS and Home Manager modules
• an overlay exposing pkgs.pi-coding-agent and pkgs.pi-coding-agent-bun
• lib.mkCodingAgent for building a configured wrapper

Important

This is not the official Nix flake for pi (there isn't one). See earendil-works/pi#2310 for context.

Quick start

nix run github:lukasl-dev/pi.nix --accept-flake-config

Or build it locally:

nix build .#coding-agent --accept-flake-config

To build the Bun-based variant instead:

nix build .#coding-agent-bun --accept-flake-config

Usage

{
  inputs.pi.url = "github:lukasl-dev/pi.nix";
}

Binary cache

Build results are pushed to pi.cachix.org, and the Bun toolchain is fetched through the nix-community cache used by bun2nix. The flake declares both substituters and public keys via nixConfig, so consumers can use --accept-flake-config or configure them explicitly:

nix.settings = {
  extra-substituters = [
    "https://pi.cachix.org"
    "https://nix-community.cachix.org"
  ];
  extra-trusted-public-keys = [
    "pi.cachix.org-1:lGeoGJaZ5ZDabuRzkcD5EBTNnDM4HJ1vqeOxlWk1Flk="
    "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="
  ];
};

NixOS

{ inputs, config, ... }:
{
  imports = [ inputs.pi.nixosModules.default ];

  programs.pi.coding-agent = {
    enable = true;
    # rules = ''Be concise.'';
    # skills = [ ./skills/my-skill ];
    # extensions = [ ./extensions/my-extension.ts ];
    # themes = [ ./themes/catppuccin-mocha.json ];
    # promptTemplates = [ ./prompts ];
    # models = ./models.json;
    # settings = {
    #   model = "gpt-5";
    # };
    # jail.enable = true;
    # extraArgs = [ "--provider" "openai" "--model" "gpt-5" ];
    # environment.PI_CODING_AGENT_DIR.value = "/path/to/pi-agent";
    # environment.OPENAI_API_KEY.file = config.sops.secrets.openai-api-key.path;
  };
}

Home Manager

{ inputs, config, ... }:
{
  imports = [ inputs.pi.homeModules.default ];

  programs.pi.coding-agent = {
    enable = true;
    # rules = ''Be concise.'';
    # skills = [ ./skills/my-skill ];
    # models = ./models.json;
    # settings.model = "gpt-5";
    # environment.PI_CODING_AGENT_DIR.value = "${config.home.homeDirectory}/.pi/agent";
    # environment.OPENAI_API_KEY.file = config.sops.secrets.openai-api-key.path;
  };
}

Overlay

{ inputs, pkgs, ... }:
{
  nixpkgs.overlays = [ inputs.pi.overlays.default ];
  environment.systemPackages = [
    pkgs.pi-coding-agent
    # or pkgs.pi-coding-agent-bun
  ];
}

Custom package

{ inputs, pkgs, ... }:
let
  pi = inputs.pi.lib.mkCodingAgent {
    inherit pkgs;
    modules = [{
      pi.coding-agent = {
        rules = ''Be concise.'';
        skills = [ ./skills/my-skill ];
        extraArgs = [ "--provider" "openai" "--model" "gpt-5" ];
      };
    }];
  };
in
pi.package

Jail

On Linux, pi can run in a jail.nix bubblewrap sandbox:

programs.pi.coding-agent.jail.enable = true;

By default, the jail has network access and a writable current directory. Pi's PI_CODING_AGENT_DIR (defaulting to ~/.pi/agent) is always mounted read-write, even when custom permissions are used. The rest of the real home directory and host tools outside the package closure remain inaccessible.

Additional permissions can be configured when more tools or files are needed. The agent configuration directory should not be included here:

programs.pi.coding-agent.jail.permissions = combinators: with combinators; [
  # Keep the default capabilities when replacing the permission list.
  network
  mount-cwd

  # Add custom tools and their runtime closures to the jailed PATH.
  (add-pkg-deps [
    pkgs.jq
    pkgs.gnumake
    pkgs.python3
  ])

  # Expose additional host files explicitly.
  (try-readonly (noescape "~/.gitconfig"))
];

add-pkg-deps is the preferred way to provide compilers, language runtimes, build tools, and other commands. Each package's bin directory is added to PATH, and the package's runtime closure is made available inside the jail. Because assigning jail.permissions replaces its default value, retain network and mount-cwd when those capabilities are wanted.

Selecting the Bun package

The NixOS/Home Manager modules still default to the npm-built package. To opt into the Bun-built variant, set package explicitly:

{ inputs, pkgs, ... }:
{
  programs.pi.coding-agent.package = inputs.pi.packages.${pkgs.system}.coding-agent-bun;
}

Options

Common options under programs.pi.coding-agent / pi.coding-agent are listed below. See the full option reference for details:

• enable
• package
• rules
• skills
• extensions
• themes
• promptTemplates
• models
• jail.enable
• jail.permissions
• extraArgs
• environment
• settings

Generate the complete option reference in Markdown or HTML with:

nix build .#docs-md
nix build .#docs-html

The outputs are available at result/index.md and result/index.html, respectively.