Understanding Workstation Config

This repo manages two platforms with standalone home-manager:

• NixOS devbox — Hetzner ARM server (system: aarch64-linux)
• nix-darwin macOS — MacBook Pro (system: aarch64-darwin)

Both share the same home-manager base config. Platform differences are isolated in dedicated modules.

Repository Structure

workstation/
├── flake.nix                 # Single flake: NixOS + nix-darwin + home-manager
├── flake.lock                # Pinned nixpkgs version
├── projects.nix              # Declarative project list (consumed by both platforms)
│
├── hosts/                    # System-level configurations
│   ├── devbox/               # NixOS system config
│   │   ├── configuration.nix # System packages, SSH, firewall, users
│   │   ├── hardware.nix      # Hetzner ARM-specific (boot, kernel)
│   │   └── disko.nix         # Disk partitioning
│   └── Y0FMQX93RR-2/        # macOS nix-darwin config
│
├── users/                    # Home-manager configurations
│   └── dev/
│       ├── home.nix           # Entry point (imports all modules below)
│       ├── home.base.nix      # Shared: git, bash, tmux, neovim, packages
│       ├── home.linux.nix     # Linux-only: systemd services, ensure-projects script
│       ├── home.darwin.nix    # macOS-only: launchd, ensure-projects activation, dotfiles migration
│       ├── opencode-config.nix # OpenCode managed config
│       ├── claude-skills.nix  # Claude Code skills deployed to ~/.claude/
│       ├── claude-hooks.nix   # Claude Code hooks (session start/stop)
│       ├── tmux.linux.nix     # Linux tmux extras
│       └── tmux.darwin.nix    # macOS tmux extras
│
├── assets/                   # Content deployed by home-manager
│   ├── claude/               # Claude skills and commands
│   ├── opencode/             # OpenCode config templates, prompts, agents
│   └── nvim/                 # Neovim Lua config (lua/user/)
│
├── secrets/                  # sops-nix encrypted secrets (devbox only)
│
├── scripts/                  # Helper scripts
│
└── .claude/                  # THIS REPO's Claude documentation
    ├── skills/               # How to understand/modify this config
    └── commands/             # Quick actions for this repo

Key Concepts

Standalone Home-Manager

Home-manager is NOT a NixOS module here. This means:

On devbox, system and user are independent (faster iteration on user config). On macOS, darwin-rebuild handles both system and home-manager in one command.

Modular home.nix Structure

home.nix is just an import list:

imports = [
  ./home.base.nix      # Cross-platform (always applied)
  ./home.linux.nix     # Guarded with lib.mkIf isLinux
  ./home.darwin.nix    # Guarded with lib.mkIf isDarwin
  ./claude-skills.nix
  ./claude-hooks.nix
  ./opencode-config.nix
  ./tmux.linux.nix
  ./tmux.darwin.nix
];

All modules are imported on both platforms. Platform-specific modules use lib.mkIf isLinux or lib.mkIf isDarwin at the top level, so they evaluate to {} on the wrong platform.

Platform Identity

CRITICAL: Never hardcode paths like /home/dev or /Users/jonathan.mohrbacher. Always use config.home.homeDirectory.

projects.nix — Declarative Project List

projects.nix is a simple attrset consumed by both platforms:

{
  my-project = { url = "[email protected]:org/repo.git"; };
}

How each platform uses it:

assets/ vs .claude/

• assets/claude/ — Skills/commands deployed TO the user's ~/.claude/
• assets/opencode/ — OpenCode config templates, prompts, custom agents
• .claude/ — Skills for working WITH this repo (not deployed anywhere)

pkgsFor Pattern

The flake defines pkgsFor once to prevent drift:

pkgsFor = system: import nixpkgs {
  inherit system;
  config.allowUnfree = true;
};

Both NixOS and home-manager use this, ensuring consistent packages.

External Flake Inputs

LLM tools come from numtide/llm-agents.nix, passed to home-manager via extraSpecialArgs:

Important: We do NOT use inputs.nixpkgs.follows for llm-agents. This preserves binary cache hits from Numtide's cache.

Merge-on-Activate Pattern

Both Claude Code and OpenCode settings use the same merge strategy:

1. Nix generates a *.managed.json (read-only, in Nix store)
2. On home-manager switch, an activation script merges managed → runtime
3. Managed keys win on conflict; runtime-only keys are preserved
4. This lets Claude Code / OpenCode write their own runtime state without clobbering

Files using this pattern:

• ~/.claude/settings.managed.json → ~/.claude/settings.json
• ~/.config/opencode/opencode.managed.json → ~/.config/opencode/opencode.json

mkOutOfStoreSymlink — Out-of-Flake Paths

When xdg.configFile.*.source points to a path outside the flake (e.g., a cloned project), Nix pure evaluation fails:

access to absolute path '/Users' is forbidden in pure evaluation mode

Solution: Use config.lib.file.mkOutOfStoreSymlink — it defers path resolution to activation time:

xdg.configFile."opencode/plugins/opencode-pigeon.ts".source =
  config.lib.file.mkOutOfStoreSymlink (
    if isDarwin
    then "${config.home.homeDirectory}/Code/opencode-pigeon/src/index.ts"
    else "${config.home.homeDirectory}/projects/opencode-pigeon/src/index.ts"
  );

Darwin Gradual Migration

On macOS, existing dotfiles may conflict with home-manager. The strategy is:

1. Disable conflicting HM programs with lib.mkForce false
2. Migrate one program at a time by removing the override
3. home.activation.prepareForHM removes stale symlinks before HM link-checking

Currently disabled on Darwin: bash, ssh, neovim (using existing dotfiles instead).

Secrets

Common Tasks

Files to Edit