# manage-nix

> Quick reference for Nix + Home Manager commands and patterns. Use for package management and dotfiles configuration.

- Author: N283T
- Repository: N283T/dotfiles
- Version: 20260120222824
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/N283T/dotfiles
- Web: https://mule.run/skillshub/@@N283T/dotfiles~manage-nix:20260120222824

---

---
name: manage-nix
description: Quick reference for Nix + Home Manager commands and patterns. Use for package management and dotfiles configuration.
allowed-tools: Bash, Read, Edit
timeout: 60000
---

# Nix + Home Manager Quick Reference

## Related

- **Agent**: `agents/nix-helper.md` - Use via Task tool for sub-agent delegation

## Common Commands

### Apply Changes
```bash
home-manager switch --flake ~/dotfiles#nagaet@aarch64-darwin
```

### Search Packages
```bash
nix search nixpkgs <query>
```

### Update Flake
```bash
cd ~/dotfiles && nix flake update
```

### Test Build (without applying)
```bash
home-manager build --flake ~/dotfiles#nagaet@aarch64-darwin
```

## Adding Packages

### 1. Find the package
```bash
nix search nixpkgs <name>
```

### 2. Add to appropriate module

**CLI tools** → `~/dotfiles/home/cli.nix`
```nix
home.packages = with pkgs; [
  new-package
];
```

**Dev tools** → `~/dotfiles/home/dev.nix`
```nix
home.packages = with pkgs; [
  new-dev-tool
];
```

**Apps** → `~/dotfiles/home/apps.nix`
```nix
home.packages = with pkgs; [
  new-app
];
```

### 3. Apply
```bash
home-manager switch --flake ~/dotfiles#nagaet@aarch64-darwin
```

## File Structure

```
~/dotfiles/
├── flake.nix           # Flake definition
├── home/
│   ├── home.nix        # Main config (imports others)
│   ├── cli.nix         # CLI tools (ripgrep, fd, jq, etc.)
│   ├── dev.nix         # Dev tools (uv, ruff, node, etc.)
│   └── apps.nix        # Apps + Claude Code config
└── claude/.claude/     # Claude configuration files
```

## Claude Code Files

To add new Claude files, edit `~/dotfiles/home/apps.nix`:

```nix
home.file = {
  ".claude/new-file".source = ../claude/.claude/new-file;
  ".claude/new-dir".source = ../claude/.claude/new-dir;
};
```

## Troubleshooting

### Error: attribute not found
```bash
# Check correct package name
nix search nixpkgs <name>
```

### Error: hash mismatch
```bash
# Update flake lock
cd ~/dotfiles && nix flake update
```

### Error: collision
Check for duplicate packages across modules.

### Verbose debugging
```bash
home-manager switch --flake ~/dotfiles#nagaet@aarch64-darwin --show-trace
```

## Rollback

```bash
# List generations
home-manager generations

# Activate previous generation
/nix/store/<hash>-home-manager-generation/activate
```

## Garbage Collection

```bash
# Remove old generations
nix-collect-garbage -d

# Check store size
du -sh /nix/store
```

## Programs vs Packages

```nix
# programs.* = Declarative config
programs.git = {
  enable = true;
  userName = "name";
};

# home.packages = Just install binary
home.packages = [ pkgs.git ];
```

Use `programs.*` when you want Home Manager to manage the config file.
Use `home.packages` when you just need the binary.