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