kenji
121 lines
4.4 KiB
Markdown
121 lines
4.4 KiB
Markdown
# 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.
|