millerson-overlay.nix/README.md

millerson.name Nix Overlay

A custom Nix overlay and flake providing additional packages not found in upstream nixpkgs, built using numtide/blueprint for streamlined flake development.

Features

• Custom packages - Additional software packaged for Nix
• Two overlay strategies - Choose between binary-cache-friendly or dependency-sharing overlays
• Blueprint-based - Uses modern Nix flake patterns with numtide/blueprint

Available Packages

Package	Description	Category
goose-cli	CLI for Goose - a local, extensible, open source AI agent that automates engineering tasks	AI Coding Agents
mcp-gateway	Universal Model Context Protocol gateway that sits between AI client and MCP tools/servers	MCP Servers
skillsmcp	MCP server that exposes Agent Skills to AI agents via the Model Context Protocol	MCP Servers

Usage

As a Flake

Add to your flake.nix inputs:

inputs.millerson-nix-overlay.url = "git+https://git.millerson.name/alex/millerson-overlay.nix.git";

Then use in your outputs:

outputs = { nixpkgs, millerson-nix-overlay, ... }: {
  nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
    system = "x86_64-linux";
    modules = [
      millerson-nix-overlay.nixosModules.default
      # ... your other modules
    ];
  };
};

As an Overlay

Option 1: Default Overlay (Binary Cache Friendly)

Uses the packages built against this flake's nixpkgs revision. Binary cache hits work best when using the same nixpkgs revision.

nixpkgs.overlays = [ millerson-nix-overlay.overlays.default ];

Option 2: Shared Nixpkgs Overlay (Dependency Sharing)

Builds packages against your system's nixpkgs, sharing dependencies with the rest of your system. No second nixpkgs evaluation, but binary cache only hits when your nixpkgs revision matches ours.

nixpkgs.overlays = [ millerson-nix-overlay.overlays.shared-nixpkgs ];

Installing Packages

With flakes enabled:

# Try a package
nix run git+https://git.millerson.name/alex/millerson-overlay.nix.git#goose-cli

# Install permanently
nix profile install git+https://git.millerson.name/alex/millerson-overlay.nix.git#goose-cli

Development

Prerequisites

• Nix with flakes enabled
• treefmt-nix for formatting (optional)

Building Packages

# Build all packages for current system
nix build .#packages

# Build specific package
nix build .#goose-cli

# Enter development shell
nix develop

Project Structure

nix-overlay/
├── flake.nix                    # Flake definition
├── overlays/                    # Overlay implementations
│   ├── default.nix             # Binary-cache-friendly overlay
│   └── shared-nixpkgs.nix      # Dependency-sharing overlay
├── packages/                    # Package definitions
│   ├── default/                # Meta-package listing all packages
│   ├── goose-cli/              # Goose CLI package
│   └── flake-inputs/           # Utility for caching flake inputs
└── README.md

Adding New Packages

1. Create a new directory under packages/<package-name>/
2. Add a package.nix with the package definition
3. Create a default.nix that imports package.nix with proper arguments
4. The package will be automatically picked up by blueprint

Example structure:

packages/my-package/
├── default.nix    # Import wrapper
└── package.nix    # Actual package definition

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.