vibecoding: replace AGENTS.md with CLAUDE.md
This commit is contained in:
71
AGENTS.md
71
AGENTS.md
@@ -1,71 +0,0 @@
|
|||||||
# AGENTS.md
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
This repository contains NixOS configurations for multiple machines using flakes, home-manager, and sops-nix for secrets.
|
|
||||||
|
|
||||||
## Working with this Repository
|
|
||||||
|
|
||||||
### DO
|
|
||||||
- Use `nix fmt` or `nix fmt .` to format files before committing (uses nixfmt-tree)
|
|
||||||
- Test builds with `nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel`
|
|
||||||
- Use the included devShell run `nix develop` to get formatting and linting tools
|
|
||||||
- When adding packages, check both overlays in `flake.nix` and `home/programs/`
|
|
||||||
- Follow the directory structure: `hosts/` for system configs, `home/` for home-manager configs
|
|
||||||
- **CRITICAL: When adding NEW files, run `git add <newfile>` BEFORE building. Nix flakes ignore untracked files in the build context, so newly added files won't be copied and builds will fail until they're git-tracked**
|
|
||||||
|
|
||||||
### DON'T
|
|
||||||
- Don't work directly on master branch, always create a new branch if editing something
|
|
||||||
- Don't run `nix flake update` to update inputs, this should only be done by the user manually
|
|
||||||
- Don't directly edit files in `secrets/` - they should be manually managed by the user
|
|
||||||
- Don't add secrets to Git
|
|
||||||
- Don't format with tools other than `nix fmt` (the formatter is defined in flake.nix)
|
|
||||||
- Don't modify `.sops.yaml` or any secrets, ask the user to do it manually
|
|
||||||
- Don't use `nix-shell` directly - use `nix develop` for the devShell environment
|
|
||||||
- Don't skip builds after configuration changes - test before pushing
|
|
||||||
- Don't mix stable and unstable packages arbitrarily in the same expression
|
|
||||||
- Don't commit without running `nix fmt` - formatted Nix is required
|
|
||||||
- **Don't try to build with newly created but untracked files - `nix build` will fail to find them**
|
|
||||||
|
|
||||||
## Specific Patterns
|
|
||||||
|
|
||||||
### Adding a New Program
|
|
||||||
- DO add to `home/packages` if no nixos or home-manager options are used.
|
|
||||||
- DO create a subdirectory in `home/programs/` if nixos or home-manager options are used.
|
|
||||||
- DO `git add` the new configuration files before attempting to build
|
|
||||||
- DON'T add programs directly to user configs unless absolutely necessary
|
|
||||||
|
|
||||||
### Modifying System Configuration
|
|
||||||
- DO check `system/` for shared configs across hosts
|
|
||||||
- DO check individual `hosts/<hostname>/` for host-specific overrides
|
|
||||||
- DON'T duplicate configuration - use `system/` modules for shared settings
|
|
||||||
|
|
||||||
### Working with Secrets
|
|
||||||
- DON'T add unencrypted secrets to the repository
|
|
||||||
- DON'T commit decrypted secrets
|
|
||||||
- DON'T add secrets, ask the user do it themselves
|
|
||||||
|
|
||||||
### Testing
|
|
||||||
- DO run `nix build .#nixosConfigurations.<hostname>.config.system.build.toplevel` to test
|
|
||||||
- DON'T push untested configuration changes
|
|
||||||
- DON'T attempt to build configurations with newly added but untracked files
|
|
||||||
|
|
||||||
### Git
|
|
||||||
If change is small, and can be described sufficiently in the summary, dont add a long
|
|
||||||
body to the commit, prefer just the summary if sufficient.
|
|
||||||
|
|
||||||
Commits should match the format:
|
|
||||||
`topic: description of change`
|
|
||||||
|
|
||||||
Some examples:
|
|
||||||
- hyprland: convert deprecated windowrules
|
|
||||||
- packages: nixfmt-rfc-style renamed
|
|
||||||
- gunter: use beta nvidia driver
|
|
||||||
|
|
||||||
|
|
||||||
## Repository Structure Guide
|
|
||||||
- `flake.nix` - Entrypoint, inputs, overlays, and configurations
|
|
||||||
- `hosts/` - System-level NixOS configs per host
|
|
||||||
- `home/` - Home-manager configs (programs, editor, window managers)
|
|
||||||
- `system/` - Shared system modules (fonts, security, services)
|
|
||||||
- `secrets/` - Encrypted secrets (managed by sops-nix)
|
|
||||||
- `scripts/` - Utility scripts
|
|
||||||
135
CLAUDE.md
Normal file
135
CLAUDE.md
Normal file
@@ -0,0 +1,135 @@
|
|||||||
|
# CLAUDE.md
|
||||||
|
|
||||||
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||||
|
|
||||||
|
## Repository Overview
|
||||||
|
|
||||||
|
This is a NixOS configuration repository using flakes for managing multiple machines (gunter, magicman). It uses home-manager for user configurations and sops-nix for secrets management. Custom packages from private git repositories are integrated via flake inputs and overlays.
|
||||||
|
|
||||||
|
## Essential Commands
|
||||||
|
|
||||||
|
### Formatting
|
||||||
|
```bash
|
||||||
|
nix fmt # Format all Nix files (uses nixfmt-tree)
|
||||||
|
nix fmt . # Same as above
|
||||||
|
```
|
||||||
|
|
||||||
|
### Building & Testing
|
||||||
|
```bash
|
||||||
|
# Test build a specific host configuration
|
||||||
|
nix build .#nixosConfigurations.gunter.config.system.build.toplevel
|
||||||
|
nix build .#nixosConfigurations.magicman.config.system.build.toplevel
|
||||||
|
|
||||||
|
# Enter development shell (includes act, actionlint, yamllint)
|
||||||
|
nix develop
|
||||||
|
```
|
||||||
|
|
||||||
|
If config clearly only affects one host, bulding for just the relevant host is enough.
|
||||||
|
Otherwise, build both.
|
||||||
|
|
||||||
|
### Common Operations
|
||||||
|
```bash
|
||||||
|
# Check flake without building
|
||||||
|
nix flake check
|
||||||
|
|
||||||
|
# Show flake outputs
|
||||||
|
nix flake show
|
||||||
|
```
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Flake Structure
|
||||||
|
- **Inputs**: Uses both stable (nixos-25.05) and unstable nixpkgs channels
|
||||||
|
- **Overlays**: `overlay-stable` provides `pkgs.stable` for stable packages; custom overlays integrate private packages (ghettoptt, huecli, nixprstatus, natstonotify, nix-packages)
|
||||||
|
- **System**: x86_64-linux primary, with multi-platform devShell support
|
||||||
|
|
||||||
|
### Directory Organization
|
||||||
|
```
|
||||||
|
├── flake.nix # Main entrypoint with overlays and host definitions
|
||||||
|
├── hosts/ # Per-host system configurations
|
||||||
|
│ ├── gunter/ # Desktop with multi-monitor, nvidia, steam
|
||||||
|
│ └── magicman/ # Laptop configuration
|
||||||
|
├── home/ # Home-manager user configurations
|
||||||
|
│ ├── hosts/ # Per-host user settings (imports packages + programs)
|
||||||
|
│ ├── editor/ # Neovim configuration
|
||||||
|
│ ├── hyprland/ # Wayland compositor with custom options
|
||||||
|
│ ├── packages/ # Simple packages (no options)
|
||||||
|
│ ├── programs/ # Programs with home-manager options (dunst, git, firefox, etc.)
|
||||||
|
│ ├── services/ # User services (backup, ghettoptt, natstonotify)
|
||||||
|
│ ├── scripts/ # User scripts
|
||||||
|
│ ├── sops/ # User secrets configuration
|
||||||
|
│ ├── ssh/ # SSH configuration
|
||||||
|
│ └── zsh/ # Shell configuration
|
||||||
|
├── system/ # Shared system-level modules
|
||||||
|
│ ├── monitoring/ # logs.nix, metrics.nix
|
||||||
|
│ ├── fonts.nix # Font configuration
|
||||||
|
│ ├── locale.nix # Localization settings
|
||||||
|
│ ├── users.nix # User account definitions
|
||||||
|
│ └── ... # Other system modules
|
||||||
|
└── secrets/ # SOPS-encrypted secrets (don't modify)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configuration Pattern
|
||||||
|
- Each host's `default.nix` imports: `configuration.nix`, `hardware-configuration.nix`, host-specific modules, `../../system`, and `../../home/hosts/<hostname>`
|
||||||
|
- Home-manager imports are in `home/hosts/<hostname>/default.nix` which imports editor, hyprland, packages, programs, services, etc.
|
||||||
|
- Shared system config goes in `system/`, host-specific overrides in `hosts/<hostname>/`
|
||||||
|
|
||||||
|
### Hyprland Custom Options
|
||||||
|
The hyprland module in `home/hyprland/default.nix` provides custom options:
|
||||||
|
- `hyprland.monitors`: List of monitor configurations
|
||||||
|
- `hyprland.extraEnv`: Environment variables
|
||||||
|
- `hyprland.extraKeybinds`: Additional keybindings
|
||||||
|
- `hyprland.extraWorkspaces`: Named workspace definitions
|
||||||
|
- `hyprland.monitorVariables`: Monitor name variables (e.g., `$mon_left`)
|
||||||
|
- `hyprland.enableGrimblast`, `hyprland.enableWacom`, `hyprland.cursorNoHardware`: Feature flags
|
||||||
|
|
||||||
|
## Critical Workflow Rules
|
||||||
|
|
||||||
|
### Git Tracking for New Files
|
||||||
|
**CRITICAL**: Nix flakes ignore untracked files. When adding new files, run `git add <newfile>` BEFORE attempting to build. Builds will fail with "file not found" errors until files are git-tracked.
|
||||||
|
|
||||||
|
### Branching
|
||||||
|
Always create a new branch for changes. Never work directly on master branch.
|
||||||
|
|
||||||
|
### Formatting
|
||||||
|
Always run `nix fmt` before committing. Formatted Nix code is required.
|
||||||
|
|
||||||
|
### Commit Messages
|
||||||
|
Format: `topic: description`
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
- `hyprland: convert deprecated windowrules`
|
||||||
|
- `packages: nixfmt-rfc-style renamed`
|
||||||
|
- `gunter: use beta nvidia driver`
|
||||||
|
|
||||||
|
Keep summaries concise. Only add commit body if needed for context.
|
||||||
|
|
||||||
|
### Forbidden Operations
|
||||||
|
- Don't run `nix flake update` (user manages input updates)
|
||||||
|
- Don't edit files in `secrets/` directory
|
||||||
|
- Don't modify `.sops.yaml`
|
||||||
|
- Don't use `nix-shell` (use `nix develop` instead)
|
||||||
|
- Don't mix stable/unstable packages arbitrarily
|
||||||
|
- Don't skip builds after configuration changes
|
||||||
|
|
||||||
|
### Adding Programs
|
||||||
|
- If no NixOS/home-manager options needed: add to `home/packages`
|
||||||
|
- If using options: create subdirectory in `home/programs/`
|
||||||
|
- Remember to `git add` new files before building
|
||||||
|
|
||||||
|
## Package Management
|
||||||
|
|
||||||
|
### Using Stable Packages
|
||||||
|
The `overlay-stable` provides access to stable nixpkgs via `pkgs.stable`:
|
||||||
|
```nix
|
||||||
|
environment.systemPackages = [ pkgs.stable.somePackage ];
|
||||||
|
```
|
||||||
|
Do not use packages from stable unless explicitly requested.
|
||||||
|
|
||||||
|
### Custom Packages
|
||||||
|
Custom packages from private repos are available via overlays:
|
||||||
|
- `pkgs.ghettoptt`
|
||||||
|
- `pkgs.huecli`
|
||||||
|
- `pkgs.nixprstatus`
|
||||||
|
- `pkgs.natstonotify`
|
||||||
|
- Plus packages from `nix-packages` overlay
|
||||||
Reference in New Issue
Block a user