docs: update AGENTS.md and CLAUDE.md
This commit is contained in:
Melvin Ragusa
223
AGENTS.md
223
AGENTS.md
@@ -1,110 +1,167 @@
|
|||||||
# AGENTS.md - NixOS Configuration Repository
|
# AGENTS.md - NixOS Configuration Guidelines
|
||||||
|
|
||||||
## 1. Project Context
|
Guidelines for AI agents working with this NixOS flake-based configuration.
|
||||||
This is a **NixOS Flake configuration** for a personal desktop system (hostname: `nix`, user: `pinj`).
|
|
||||||
It relies on modern Nix features (Flakes, experimental commands) and a modular architecture.
|
|
||||||
|
|
||||||
## 2. Build & Validation Commands
|
## Project Overview
|
||||||
|
|
||||||
### Core Workflows
|
Modular NixOS configuration for a desktop workstation using Nix flakes.
|
||||||
Use these commands to verify your changes. **Always run the test command before asking the user to switch.**
|
|
||||||
|
**Tech Stack:** NixOS, Nix Flakes, Fish shell, Wayland (Niri), AMD GPU
|
||||||
|
|
||||||
|
## Repository Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
nixos/
|
||||||
|
├── flake.nix # Flake inputs and outputs
|
||||||
|
├── configuration.nix # Main config (imports all modules)
|
||||||
|
├── hardware-configuration.nix # Auto-generated (don't edit)
|
||||||
|
└── modules/
|
||||||
|
├── apps.nix # User applications
|
||||||
|
├── desktop.nix # Wayland, portals, polkit
|
||||||
|
├── dev.nix # Docker, dev tools, languages
|
||||||
|
├── gaming.nix # Steam, Gamemode, Wine
|
||||||
|
├── gpu-amd.nix # AMD GPU drivers
|
||||||
|
├── shell.nix # Fish shell config
|
||||||
|
├── theming.nix # Fonts, themes, cursors
|
||||||
|
└── ... # Other modules
|
||||||
|
```
|
||||||
|
|
||||||
|
## Build Commands
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1. SYNTAX CHECK (Fastest)
|
# Test configuration without switching (recommended first)
|
||||||
# Checks for basic syntax errors without evaluating the entire system
|
sudo nixos-rebuild test --flake .#nixos
|
||||||
nix-instantiate --parse configuration.nix
|
|
||||||
|
|
||||||
# 2. FLAKE CHECK (Unit Tests)
|
# Switch to new configuration
|
||||||
# Validates flake structure and evaluates outputs. Use this to ensure no regression.
|
sudo nixos-rebuild switch --flake .#nixos
|
||||||
|
|
||||||
|
# Quick syntax validation
|
||||||
nix flake check
|
nix flake check
|
||||||
|
|
||||||
# 3. DRY RUN (Integration Test)
|
# Update all flake inputs
|
||||||
# Builds the system and tries to activate it in a VM or checks for conflicts
|
|
||||||
# without modifying the bootloader or switching the current system.
|
|
||||||
sudo nixos-rebuild test --flake .#nixos
|
|
||||||
```
|
|
||||||
|
|
||||||
### Deployment
|
|
||||||
Only run these when explicitly requested by the user:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Build (create derivation but don't switch)
|
|
||||||
sudo nixos-rebuild build --flake .#nixos
|
|
||||||
|
|
||||||
# Switch (apply changes to live system)
|
|
||||||
sudo nixos-rebuild switch --flake .#nixos
|
|
||||||
```
|
|
||||||
|
|
||||||
### Maintenance
|
|
||||||
```bash
|
|
||||||
# Update inputs (e.g. nixpkgs)
|
|
||||||
nix flake update
|
nix flake update
|
||||||
|
|
||||||
# Format all nix files
|
# Garbage collection
|
||||||
nixfmt *.nix modules/*.nix
|
sudo nix-collect-garbage --delete-older-than 14d
|
||||||
```
|
```
|
||||||
|
|
||||||
## 3. Code Style & Conventions
|
## Code Style Guidelines
|
||||||
|
|
||||||
### Visual Structure
|
### File Structure
|
||||||
Maintain the project's visual hierarchy. Use decorative comments to separate major sections.
|
|
||||||
|
Each module follows this pattern:
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
# ═══════════════════════════════════════════════════════════════
|
# modules/example.nix
|
||||||
# SECTION NAME (UPPERCASE)
|
# Brief description of what this module does
|
||||||
# ═══════════════════════════════════════════════════════════════
|
{
|
||||||
|
config,
|
||||||
|
pkgs,
|
||||||
|
lib,
|
||||||
|
...
|
||||||
|
}:
|
||||||
|
|
||||||
|
{
|
||||||
|
# Module content here
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Nix Formatting
|
### Formatting
|
||||||
- **Indentation:** 2 spaces.
|
|
||||||
- **Lists:** Use `with pkgs; [ ... ]` for package lists to reduce verbosity.
|
- **Formatter**: `nixfmt`
|
||||||
- **Line Length:** Soft limit 100 chars, hard limit 120.
|
- **Indentation**: 2 spaces (no tabs)
|
||||||
- **Functions:** Use standard module arguments: `{ config, pkgs, lib, ... }:`.
|
- **Line length**: ~100 chars, break long lists
|
||||||
|
|
||||||
|
### Naming Conventions
|
||||||
|
|
||||||
|
- **Files**: `kebab-case.nix` (e.g., `gpu-amd.nix`)
|
||||||
|
- **Options**: NixOS convention, camelCase (e.g., `extraGroups`)
|
||||||
|
|
||||||
|
### Comments & Headers
|
||||||
|
|
||||||
|
- Major sections: `# ═══ SECTION NAME ═══` (full line of `═`)
|
||||||
|
- Subsections: `# ─── Subsection ───` (full line of `─`)
|
||||||
|
- Inline comments for non-obvious settings
|
||||||
|
|
||||||
|
### Package Lists & Attribute Sets
|
||||||
|
|
||||||
### Module Pattern
|
|
||||||
All functionality should be modularized in `./modules/`.
|
|
||||||
- **Filename:** `kebab-case.nix` (e.g., `gpu-amd.nix`).
|
|
||||||
- **Structure:**
|
|
||||||
```nix
|
```nix
|
||||||
{ config, pkgs, lib, ... }: {
|
|
||||||
# Options
|
|
||||||
programs.foo.enable = true;
|
|
||||||
|
|
||||||
# Packages
|
|
||||||
environment.systemPackages = with pkgs; [
|
environment.systemPackages = with pkgs; [
|
||||||
foo-pkg
|
# Category header
|
||||||
|
package1
|
||||||
|
package2
|
||||||
|
];
|
||||||
|
|
||||||
|
# Short sets inline: { enable = true; }
|
||||||
|
# Multi-line with indentation:
|
||||||
|
services.example = {
|
||||||
|
enable = true;
|
||||||
|
settings.Option = "value";
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Important Notes
|
||||||
|
|
||||||
|
1. **hardware-configuration.nix**: Auto-generated, never edit manually
|
||||||
|
2. **Username**: `pinj` - used throughout the config
|
||||||
|
3. **User groups**: Distributed across modules via `users.users.pinj.extraGroups`
|
||||||
|
4. **GUI apps**: Managed via `nix profile`, not system packages
|
||||||
|
5. **Unfree packages**: Enabled in `configuration.nix`
|
||||||
|
6. **State version**: `26.05` - don't change unless migrating
|
||||||
|
|
||||||
|
## Flake Inputs
|
||||||
|
|
||||||
|
| Input | Purpose |
|
||||||
|
|-------|---------|
|
||||||
|
| `nixpkgs` | NixOS unstable channel |
|
||||||
|
| `nix-cachyos-kernel` | CachyOS optimized kernel |
|
||||||
|
| `noctalia` | Desktop shell |
|
||||||
|
| `vicinae` | Application launcher |
|
||||||
|
|
||||||
|
## Common Patterns
|
||||||
|
|
||||||
|
### Adding a New Module
|
||||||
|
|
||||||
|
1. Create `modules/newmodule.nix` with standard header
|
||||||
|
2. Add import to `configuration.nix`
|
||||||
|
3. Test with `sudo nixos-rebuild test --flake .#nixos`
|
||||||
|
|
||||||
|
### Adding System Packages
|
||||||
|
|
||||||
|
Add to the relevant module's `environment.systemPackages`:
|
||||||
|
```nix
|
||||||
|
environment.systemPackages = with pkgs; [
|
||||||
|
newpackage
|
||||||
|
];
|
||||||
|
```
|
||||||
|
|
||||||
|
### Adding User to Group
|
||||||
|
|
||||||
|
```nix
|
||||||
|
users.users.pinj.extraGroups = [ "groupname" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
### Using Flake Inputs
|
||||||
|
|
||||||
|
```nix
|
||||||
|
# Add inputs to module arguments
|
||||||
|
{ config, pkgs, inputs, lib, ... }:
|
||||||
|
|
||||||
|
{
|
||||||
|
environment.systemPackages = [
|
||||||
|
inputs.flakename.packages.${pkgs.system}.default
|
||||||
];
|
];
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Naming & Variables
|
### Adding User GUI Apps
|
||||||
- **Inputs:** Reference flake inputs via `inputs.name` (passed via `specialArgs`).
|
|
||||||
- **Packages:** Use `pkgs.packageName`.
|
|
||||||
- **User:** The primary user `pinj` is defined in `configuration.nix`.
|
|
||||||
- **Groups:** Add user to groups via `extraGroups` in specific modules (e.g., `docker` group in `dev.nix`).
|
|
||||||
|
|
||||||
## 4. Agent Guidelines
|
```bash
|
||||||
|
nix profile install nixpkgs#packagename
|
||||||
|
```
|
||||||
|
|
||||||
### ⚠️ Critical Safety Rules
|
## Error Handling
|
||||||
1. **Secrets:** NEVER commit secrets (tokens, keys, passwords). Check `.gitignore`.
|
|
||||||
2. **Hardware Config:** Do NOT modify `hardware-configuration.nix` unless explicitly checking for new drives/mounts. It is auto-generated.
|
|
||||||
3. **State Version:** Do NOT change `system.stateVersion` ("26.05").
|
|
||||||
|
|
||||||
### Navigation & Editing
|
- NixOS fails builds on errors - this is the primary validation
|
||||||
- **Absolute Paths:** When using tools, always resolve paths fully (e.g., `/home/pinj/nixos/modules/dev.nix`).
|
- Always test with `nixos-rebuild test` before `switch`
|
||||||
- **Read First:** Always read `configuration.nix` to see active imports before creating new modules.
|
- Use `nix flake check` for quick syntax validation
|
||||||
- **Search:** Use `grep` to find where existing programs are configured (e.g., `grep -r "firefox" .`).
|
|
||||||
|
|
||||||
### Troubleshooting Common Errors
|
|
||||||
- **"Option does not exist":** You might be missing an import in `configuration.nix` or using a home-manager option in a system module.
|
|
||||||
- **"Hash mismatch":** If updating a `fetchurl` or flake input, ensure hashes are updated.
|
|
||||||
- **"ReadOnly":** You cannot edit files in the `/nix/store`. Only edit files in `/home/pinj/nixos`.
|
|
||||||
|
|
||||||
## 5. Directory Structure
|
|
||||||
|
|
||||||
| Path | Purpose |
|
|
||||||
|------|---------|
|
|
||||||
| `flake.nix` | Entry point, dependencies (inputs), and outputs. |
|
|
||||||
| `configuration.nix` | System glue. Imports modules, sets defaults, defines user. |
|
|
||||||
| `modules/` | Feature-specific configs (desktop, dev, gaming, etc.). |
|
|
||||||
| `hardware-configuration.nix` | Hardware scan (do not edit manually). |
|
|
||||||
|
|||||||
75
CLAUDE.md
Normal file
75
CLAUDE.md
Normal file
@@ -0,0 +1,75 @@
|
|||||||
|
# CLAUDE.md
|
||||||
|
|
||||||
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
This is "Atlas" - a modular, flake-based NixOS configuration for a desktop workstation. The system is AMD-specific (CPU + GPU) and optimized for gaming, development, and daily use.
|
||||||
|
|
||||||
|
## Common Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Test configuration without switching (validate before applying)
|
||||||
|
sudo nixos-rebuild test --flake .#nixos
|
||||||
|
|
||||||
|
# Apply configuration
|
||||||
|
sudo nixos-rebuild switch --flake .#nixos
|
||||||
|
|
||||||
|
# Build and set as boot default (without switching)
|
||||||
|
sudo nixos-rebuild boot --flake .#nixos
|
||||||
|
|
||||||
|
# Update all flake inputs
|
||||||
|
nix flake update
|
||||||
|
|
||||||
|
# Update specific input
|
||||||
|
nix flake lock --update-input nixpkgs
|
||||||
|
|
||||||
|
# Garbage collection
|
||||||
|
sudo nix-collect-garbage --delete-older-than 14d
|
||||||
|
```
|
||||||
|
|
||||||
|
Shell aliases are defined in `modules/shell.nix`: `rebuild`, `rebuild-test`, `rebuild-boot`, `update`, `gc-nix`.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
**Entry Points:**
|
||||||
|
- `flake.nix` - Flake definition with inputs (nixpkgs unstable, nix-cachyos-kernel, noctalia shell, vicinae launcher)
|
||||||
|
- `configuration.nix` - Main config that imports all modules, defines boot, networking, user, and nix settings
|
||||||
|
- `hardware-configuration.nix` - Auto-generated by `nixos-generate-config` (do not edit manually)
|
||||||
|
|
||||||
|
**Modular Structure:**
|
||||||
|
All feature configurations live in `modules/` as standalone NixOS modules:
|
||||||
|
- `desktop.nix` - XDG portals, Wayland, polkit, launcher (Vicinae)
|
||||||
|
- `gpu-amd.nix` - AMD drivers, Vulkan, VA-API, CoreCtrl
|
||||||
|
- `gaming.nix` - Steam, Gamemode, Wine/Proton, kernel tweaks
|
||||||
|
- `dev.nix` - Docker, Node.js, Rust, build tools, CLI utilities
|
||||||
|
- `shell.nix` - Fish shell config, aliases, plugins
|
||||||
|
- `services.nix` - fstrim, zram, avahi, profile-sync-daemon, earlyoom
|
||||||
|
- `audio.nix`, `theming.nix`, `power.nix`, `virtualization.nix`, `navidrome.nix`, `apps.nix`
|
||||||
|
|
||||||
|
Each module follows the pattern: `{ config, pkgs, lib, ... }: { ... }`
|
||||||
|
|
||||||
|
**Package Management Philosophy:**
|
||||||
|
- System packages (`environment.systemPackages`): Services, hardware support, desktop infrastructure, build tools
|
||||||
|
- User packages (`nix profile`): GUI apps and fast-updating tools - managed independently with `update-apps` alias
|
||||||
|
|
||||||
|
## Code Conventions
|
||||||
|
|
||||||
|
- 2-space indentation
|
||||||
|
- Standard module signature: `{ config, pkgs, lib, ... }:`
|
||||||
|
- Package lists use `with pkgs; [ ... ]` syntax
|
||||||
|
- Decorative comment separators (`# ═══...`) for major sections
|
||||||
|
|
||||||
|
## Critical Rules
|
||||||
|
|
||||||
|
1. **Never modify `hardware-configuration.nix`** - it's auto-generated
|
||||||
|
2. **Never change `system.stateVersion`** (currently 26.05)
|
||||||
|
3. **Always validate with `rebuild-test` before switching**
|
||||||
|
4. User groups are distributed across modules (docker in dev.nix, gamemode in gaming.nix, corectrl in gpu-amd.nix, libvirtd in virtualization.nix)
|
||||||
|
|
||||||
|
## Key System Details
|
||||||
|
|
||||||
|
- **Kernel**: CachyOS with x86_64-v3 optimizations, scx_lavd scheduler
|
||||||
|
- **Desktop**: Niri compositor, Ly display manager, Ghostty terminal
|
||||||
|
- **User**: `pinj` with Fish shell (Zsh as fallback)
|
||||||
|
- **State Version**: 26.05
|
||||||
1571
pacman.txt
1571
pacman.txt
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user