# millerson.name Nix Overlay

A custom Nix overlay and flake providing additional packages not found in upstream nixpkgs, built using [numtide/blueprint](https://github.com/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 |
|---------|-------------|----------|
| `container-use` | Containerized environments for coding agents | AI Coding Agents |
| `goose-cli` | CLI for Goose - a local, extensible, open source AI agent that automates engineering tasks | AI Coding Agents |
| `graphify` | Turn any folder of code, docs, papers, images, or videos into a queryable knowledge graph | 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 |
| `kubernetes-mcp-server` | Model Context Protocol (MCP) server for Kubernetes and OpenShift | MCP Servers |

## Usage

### As a Flake

Add to your `flake.nix` inputs:

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

Then use in your outputs:

```nix
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.

```nix
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.

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

### Installing Packages

With flakes enabled:

```bash
# 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](https://github.com/numtide/treefmt-nix) for formatting (optional)

### Building Packages

```bash
# 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
├── treefmt.toml                 # Code formatting configuration (nixfmt)
├── overlays/                    # Overlay implementations
│   ├── default.nix             # Binary-cache-friendly overlay
│   └── shared-nixpkgs.nix      # Dependency-sharing overlay
├── packages/                    # Package definitions
│   ├── default/                # Meta-package listing all packages
│   ├── flake-inputs/           # Utility for caching flake inputs
│   ├── goose-cli/              # Goose AI agent CLI
│   ├── graphify/               # Knowledge graph generator for code folders
│   ├── mcp-gateway/            # MCP protocol gateway
│   └── skillsmcp/              # MCP server for Agent Skills
└── 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](LICENSE) file for details.

## Contributing

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