Nix Package Development for AgentStation

Expert assistance for maintaining Nix packages in the `agentstation/nix-packages` repository. This skill provides guidance on building, testing, and updating Nix derivations for AgentStation CLI tools distributed via Nix flakes.

What This Skill Does

This skill helps you work with the AgentStation Nix packages repository, which provides Nix derivations for:

The repository enables distribution via Nix, Devbox, and other Nix-compatible systems.

Repository Structure Understanding

Before making changes, understand the repository layout:

```

agentstation/nix-packages/

├── flake.nix # Main flake exporting all packages

├── flake.lock # Lock file for reproducibility (auto-generated)

├── packages/

│ ├── pocket/

│ │ └── default.nix # Go package derivation

│ └── tydirium/

│ └── default.nix # Shell script derivation

├── README.md # User installation instructions

└── CLAUDE.md # Development guidance

```

Step-by-Step Instructions

1. Testing Package Builds

Always test packages before committing changes:

**Test individual package:**

```bash

Build the package

nix build .#pocket

nix build .#tydirium

Test running it

nix run .#pocket -- --help

nix run .#tydirium -- --help

Enter development shell for testing

nix develop

```

**Validate entire flake:**

```bash

nix flake check

```

2. Updating Package Versions

When a new version of a tool is released, follow this process:

**Step 2.1: Update version in `default.nix`**

Locate the package's `default.nix` file (e.g., `packages/pocket/default.nix`) and update:

**Step 2.2: Update source hash**

Set a placeholder hash first:

```nix

src = fetchFromGitHub {

# ... owner, repo, rev ...

hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";

};

```

Then build to get the correct hash:

```bash

nix build .#pocket

```

The error message will show:

```

error: hash mismatch in fixed-output derivation

specified: sha256-AAAA...

got: sha256-<REAL_HASH>

```

Copy the "got" hash and update `default.nix`.

**Step 2.3: For Go packages, update vendorHash**

Go packages require updating `vendorHash` for dependencies:

```nix

vendorHash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";

```

Build again to get the correct vendor hash:

```bash

nix build .#pocket

```

Update with the hash from the error message.

**Step 2.4: Test thoroughly**

After updating hashes:

```bash

Build succeeds

nix build .#pocket

Run works correctly

nix run .#pocket -- --version

Check installed files

ls -la result/bin/

ls -la result/share/

```

**Step 2.5: Update flake.lock**

```bash

nix flake update

```

3. Package-Specific Considerations

**For Go packages (like pocket):**

```nix

postInstall = ''

installShellCompletion --cmd pocket \

--bash <($out/bin/pocket completion bash) \

--fish <($out/bin/pocket completion fish) \

--zsh <($out/bin/pocket completion zsh)

'';

```

**For shell scripts (like tydirium):**

```nix

nativeBuildInputs = [ makeWrapper ];

installPhase = ''

install -Dm755 tydirium $out/bin/tydirium

wrapProgram $out/bin/tydirium \

--prefix PATH : ${lib.makeBinPath [ dnsutils ]}

'';

```

4. Adding New Packages

When adding a new AgentStation tool:

**Step 4.1: Create package directory**

```bash

mkdir -p packages/<tool-name>

```

**Step 4.2: Write `default.nix`**

Choose the appropriate builder:

**Step 4.3: Export in `flake.nix`**

Add to packages output:

```nix

packages = {

pocket = pkgs.callPackage ./packages/pocket {};

tydirium = pkgs.callPackage ./packages/tydirium {};

<tool-name> = pkgs.callPackage ./packages/<tool-name> {};

};

```

**Step 4.4: Test the new package**

```bash

nix build .#<tool-name>

nix run .#<tool-name> -- --help

nix flake check

```

5. Flake Management

**Update all inputs:**

```bash

nix flake update

```

**Check flake metadata:**

```bash

nix flake metadata

```

**Show available outputs:**

```bash

nix flake show

```

**Format Nix files:**

```bash

nix fmt

```

6. Integration with Homebrew

This repository complements `agentstation/homebrew-tap`:

7. Troubleshooting Guide

**Hash mismatch errors:**

**Missing dependencies at runtime:**

**Flake evaluation errors:**

**Build failures:**

Important Constraints

1. **Never commit with placeholder hashes** - Always resolve to real SHA256 hashes

2. **Test before committing** - Run `nix build` and `nix run` for all modified packages

3. **Maintain reproducibility** - Update `flake.lock` after version changes

4. **Include completions** - Shell completions, man pages, and documentation should be installed

5. **Handle runtime deps** - Scripts must have access to required system tools

6. **Follow Nix conventions** - Use appropriate builders and standard phase overrides

Examples

**Example: Updating pocket to version 0.3.0**

```bash

1. Edit packages/pocket/default.nix

Update version = "0.2.0" to version = "0.3.0"

Update rev = "v0.2.0" to rev = "v0.3.0"

Set hash = "sha256-AAAA..."; (placeholder)

Set vendorHash = "sha256-AAAA..."; (placeholder)

2. Build to get source hash

nix build .#pocket

Copy the "got" hash, update hash in default.nix

3. Build again to get vendor hash

nix build .#pocket

Copy the "got" hash, update vendorHash in default.nix

4. Test the package

nix build .#pocket

nix run .#pocket -- --version

5. Update flake.lock

nix flake update

6. Commit changes

git add packages/pocket/default.nix flake.lock

git commit -m "pocket: 0.2.0 -> 0.3.0"

```

**Example: Adding runtime dependency to shell script**

```nix

{ lib, stdenv, fetchFromGitHub, makeWrapper, dnsutils, curl }:

stdenv.mkDerivation rec {

# ... pname, version, src ...

nativeBuildInputs = [ makeWrapper ];

installPhase = ''

install -Dm755 script.sh $out/bin/script

wrapProgram $out/bin/script \

--prefix PATH : ${lib.makeBinPath [ dnsutils curl ]}

'';

}

```

Reference Links