Skip to content

CLAUDE.md

Latest commit

 

History

History
92 lines (70 loc) · 3.07 KB

CLAUDE.md

File metadata and controls

92 lines (70 loc) · 3.07 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

bella-nix is a NixOS configuration management system using Nix flakes for declarative, reproducible infrastructure. It manages multiple hosts with shared, composable modules.

Commands

Enter the development shell (required for all commands):

nix develop

The dev shell automatically loads Nushell with the bnix commands:

bnix host bootstrap <hostname>   # Bootstrap new machine (formats disk, sets up Tailscale)
bnix host template <hostname>    # Create host template files
bnix host deploy                 # Deploy config to existing host via deploy-rs
bnix host delete <hostname>      # Remove a host from the repo

Direct Nix commands:

nix flake check                  # Validate flake structure
nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel

Architecture

Module System

All modules expose flake.modules.nixos.<name> and are auto-loaded by haumea from src/modules/. Every host automatically imports the base module plus disko and agenix.

Module hierarchy:

  • base/ - Core system defaults (user, home-manager, nix settings, boot)
  • profiles/ - Composable feature groups that bundle related modules:
    • cli - Shell tools (nushell, helix, git, etc.)
    • desktop - GUI environment (niri, wezterm, stylix, zen browser)
    • server - Server-specific config
    • deployer / deployable - Remote deployment capabilities
  • programs/ - Individual application configurations
  • services/ - System services (tailscale, secrets, preservation)
  • system/ - Low-level system config (bluetooth, zram, localization)

Host Configuration

Hosts live in src/hosts/<hostname>/ with:

  • configuration.nix - Main config, imports modules from profiles/programs
  • disk-configuration.nix - Disko disk layout
  • hardware-configuration.nix - Hardware-specific settings
  • facter.json - Hardware facts (generated by nixos-facter)
  • ssh_host_ed25519_key.pub - Host public key for agenix secrets

Key Patterns

Module definition pattern (all modules follow this):

{inputs, ...}: {
  flake.modules.nixos.<moduleName> = {
    imports = with inputs.self.modules.nixos; [ ... ];
    # configuration
  };
}

Host configuration imports profiles and individual modules:

{inputs}: { config, lib, ... }: {
  imports = with inputs.self.modules.nixos; [
    cli
    desktop
    discord
    # ...
  ];
}

Key Files

  • flake.nix - Flake definition, inputs, module loading logic
  • vars.nix - Global variables (username, email, tailscale domain)
  • src/modules/base/constants.nix - Exposes systemConstants option set

External Inputs

Key flake inputs: nixpkgs (unstable), home-manager, niri-flake (Wayland compositor), stylix (theming), disko (disk management), agenix/agenix-rekey (secrets), deploy-rs (deployment), preservation (state persistence).

User Environment

The user's default shell is Nushell. When suggesting shell commands, use Nushell syntax instead of Bash.