add(CLAUDE): more info
This commit is contained in:
kenji
@@ -5,9 +5,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|||||||
## Build Commands
|
## Build Commands
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Rebuild and switch to new configuration
|
# Rebuild and switch to new configuration (desktop x86_64)
|
||||||
sudo nixos-rebuild switch --flake ~/.config/nixos/#hakase
|
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
|
# Manage SOPS secrets
|
||||||
nix-shell -p sops --run "sops secrets/secrets.yaml"
|
nix-shell -p sops --run "sops secrets/secrets.yaml"
|
||||||
nix-shell -p sops --run "sops updatekeys secrets/secrets.yaml"
|
nix-shell -p sops --run "sops updatekeys secrets/secrets.yaml"
|
||||||
@@ -15,65 +21,100 @@ nix-shell -p sops --run "sops updatekeys secrets/secrets.yaml"
|
|||||||
|
|
||||||
## Architecture Overview
|
## Architecture Overview
|
||||||
|
|
||||||
This is a modular, flake-based NixOS configuration for a single host (`hakase`).
|
This is a modular, flake-based NixOS configuration supporting two hosts: `hakase` (x86_64 desktop) and `macbook` (aarch64 Apple Silicon).
|
||||||
|
|
||||||
### Key Entry Points
|
### Key Entry Points
|
||||||
|
|
||||||
- `flake.nix` - Declares inputs and creates NixOS configuration
|
- `flake.nix` - Declares inputs and creates both NixOS configurations (hakase, macbook)
|
||||||
- `config.nix` - Central configuration values (username, hostname, paths, theme settings, bookmarks)
|
- `config.nix` - Central configuration values separated by host (hakase, macbook keys)
|
||||||
- `hosts/hakase/configuration.nix` - Host-level entry point that imports system modules
|
- `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
|
### Module Organization
|
||||||
|
|
||||||
**Two-tier module system:**
|
**Three-tier system:**
|
||||||
- `modules/nixos/` - NixOS system-level modules (boot, kernel, services, hardware)
|
1. **System modules** (`modules/nixos/`) - NixOS-level settings (boot, kernel, services, hardware)
|
||||||
- `modules/home/` - Home Manager user-level modules (imported via `home/hakase.nix`)
|
2. **Home Manager modules** (`modules/home/`) - User-level environment and applications
|
||||||
|
3. **Application configs** (`apps/`) - Per-application configuration directories with `default.nix` files
|
||||||
|
|
||||||
**Application configs:** Each application has its own directory in `apps/` with a `default.nix` and optional sub-modules (e.g., `apps/hyprland/hypr/*.nix` for Hyprland settings).
|
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
|
### Configuration Flow
|
||||||
|
|
||||||
```
|
```
|
||||||
flake.nix
|
flake.nix (outputs)
|
||||||
└─ nixosConfigurations.hakase
|
├─ hakase (x86_64-linux)
|
||||||
├─ hosts/hakase/configuration.nix
|
│ ├─ hosts/hakase/configuration.nix
|
||||||
│ └─ modules/nixos/default.nix (imports all system modules)
|
│ │ └─ modules/nixos/default.nix (imports system modules)
|
||||||
└─ home-manager
|
│ └─ home-manager
|
||||||
└─ home/hakase.nix
|
│ └─ home/hakase.nix
|
||||||
└─ modules/home/* → apps/*
|
│ └─ 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
|
### Module Pattern
|
||||||
|
|
||||||
Modules receive these parameters:
|
Modules receive standard NixOS parameters plus custom ones:
|
||||||
```nix
|
```nix
|
||||||
{ pkgs, config, myConfig, inputs, ... }:
|
{ pkgs, config, lib, myConfig, inputs, system, ... }:
|
||||||
```
|
```
|
||||||
|
|
||||||
Access configuration values via `myConfig`:
|
**Key patterns:**
|
||||||
```nix
|
- Access host config: `myConfig.nixos.username`, `myConfig.terminal.default`
|
||||||
myConfig.nixos.username # "hakase"
|
- Use host-specific packages: `pkgs.unstable` (from nixpkgs), `inputs.neovim` (from flake inputs)
|
||||||
myConfig.nixos.hostname # "hakase"
|
- Reference other modules via `config` (e.g., `config.home.homeDirectory`)
|
||||||
myConfig.terminal.default # Terminal emulator
|
- Conditional logic: Check `system` or `myConfig` values
|
||||||
myConfig.hyprland.monitors # Monitor configuration
|
|
||||||
```
|
|
||||||
|
|
||||||
### Secrets Management
|
### Secrets Management
|
||||||
|
|
||||||
Uses SOPS for encrypted secrets. Keys stored at `~/.config/sops/age/keys.txt`.
|
SOPS-encrypted secrets stored in `secrets/secrets.yaml`. Age key at `~/.config/sops/age/keys.txt`.
|
||||||
|
|
||||||
Access secrets in modules:
|
In modules, reference secrets via:
|
||||||
```nix
|
```nix
|
||||||
config.sops.secrets.secret_name.path
|
config.sops.secrets.secret_name.path
|
||||||
```
|
```
|
||||||
|
|
||||||
## Key Technologies
|
## Key Technologies
|
||||||
|
|
||||||
- **Hyprland** with UWSM (systemd session management)
|
- **Hyprland** with UWSM (systemd user session management)
|
||||||
- **Stylix** for system-wide theming from wallpaper colors
|
- **Matugen** for automatic system-wide theming from wallpaper colors
|
||||||
- **Home Manager** for user environment
|
- **Home Manager** for user environment and program configuration
|
||||||
- **nixovim** flake for Neovim 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
|
## Git Commit Convention
|
||||||
|
|
||||||
Use conventional commits: `feat(scope):`, `fix(scope):`, `refactor:`, `add:`, `remove:`, `cleanup:`
|
Use conventional commits with scope: `feat(scope):`, `fix(scope):`, `refactor:`, `add:`, `remove:`, `cleanup:`
|
||||||
|
|
||||||
|
Common scopes: `nixos`, `home`, `apps`, `config`, `modules`, `hyprland`, `firefox`, etc.
|
||||||
|
|||||||
Reference in New Issue
Block a user