# CLAUDE.md

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

## Build Commands

```bash
# Rebuild and switch to new configuration (desktop x86_64)
sudo nixos-rebuild switch --flake ~/.config/nixos/#hakase

# Rebuild MacBook configuration (aarch64)
sudo nixos-rebuild switch --flake ~/.config/nixos/#macbook

# Dry-run build to check for errors without applying
sudo nixos-rebuild build --flake ~/.config/nixos/#hakase

# Manage SOPS secrets
nix-shell -p sops --run "sops secrets/secrets.yaml"
nix-shell -p sops --run "sops updatekeys secrets/secrets.yaml"
```

## Architecture Overview

This is a modular, flake-based NixOS configuration supporting two hosts: `hakase` (x86_64 desktop) and `macbook` (aarch64 Apple Silicon).

### Key Entry Points

- `flake.nix` - Declares inputs and creates both NixOS configurations (hakase, macbook)
- `config.nix` - Central configuration values separated by host (hakase, macbook keys)
- `hosts/{hakase,macbook}/configuration.nix` - Host-level entry points importing system modules
- `home/hakase.nix` - Home Manager entry point for user environment (referenced from flake)

### Module Organization

**Three-tier system:**
1. **System modules** (`modules/nixos/`) - NixOS-level settings (boot, kernel, services, hardware)
2. **Home Manager modules** (`modules/home/`) - User-level environment and applications
3. **Application configs** (`apps/`) - Per-application configuration directories with `default.nix` files

Examples:
- `apps/hyprland/default.nix` + `apps/hyprland/hypr/*.nix` - Hyprland compositor config
- `apps/firefox/default.nix` - Browser with bookmarks and theming
- `apps/ghostty/default.nix` - Terminal emulator
- `apps/neovim/default.nix` - Editor (via nixovim external flake)

### Configuration Flow

```
flake.nix (outputs)
  ├─ hakase (x86_64-linux)
  │   ├─ hosts/hakase/configuration.nix
  │   │   └─ modules/nixos/default.nix (imports system modules)
  │   └─ home-manager
  │       └─ home/hakase.nix
  │           └─ modules/home/* (imports Home Manager modules)
  │               └─ apps/* (application configurations)
  │
  └─ macbook (aarch64-linux)
      ├─ hosts/macbook/configuration.nix
      │   └─ modules/nixos/default.nix
      └─ Similar home-manager structure

config.nix provides myConfig via specialArgs to both configurations
```

### Configuration Structure (config.nix)

The `config.nix` file defines host-specific configuration under `hakase` and `macbook` keys. Common values include:

```nix
myConfig = {
  nixos = { username, hostname, timezone }
  git = { username, email, defaultBranch }
  theme = { mode }  # "dark" or "light"
  terminal = { default, font, aliases }
  font = { monospace, monospaceScript, sans }
  hyprland = { monitors, wallpaper, kb_options }
  firefox = { bookmarks, newtabpage }
  # ... more app-specific configs
}
```

To add a host-specific override, define it in the host's `myConfig` section in `config.nix`. The flake passes `allConfig.{hostname}` as specialArgs, so modules access the correct host configuration.

### Module Pattern

Modules receive standard NixOS parameters plus custom ones:
```nix
{ pkgs, config, lib, myConfig, inputs, system, ... }:
```

**Key patterns:**
- Access host config: `myConfig.nixos.username`, `myConfig.terminal.default`
- Use host-specific packages: `pkgs.unstable` (from nixpkgs), `inputs.neovim` (from flake inputs)
- Reference other modules via `config` (e.g., `config.home.homeDirectory`)
- Conditional logic: Check `system` or `myConfig` values

### Secrets Management

SOPS-encrypted secrets stored in `secrets/secrets.yaml`. Age key at `~/.config/sops/age/keys.txt`.

In modules, reference secrets via:
```nix
config.sops.secrets.secret_name.path
```

## Key Technologies

- **Hyprland** with UWSM (systemd user session management)
- **Matugen** for automatic system-wide theming from wallpaper colors
- **Home Manager** for user environment and program configuration
- **nixovim** external flake for Neovim configuration (treesitter disabled due to read-only NixOS constraints)
- **SOPS-Nix** for secrets encryption
- **CachyOS kernel** on hakase (x86_64), **Asahi Linux** on macbook (aarch64)

## Git Commit Convention

Use conventional commits with scope: `feat(scope):`, `fix(scope):`, `refactor:`, `add:`, `remove:`, `cleanup:`

Common scopes: `nixos`, `home`, `apps`, `config`, `modules`, `hyprland`, `firefox`, etc.