Skip to content

AGENTS.md

Latest commit

 

History

History
172 lines (123 loc) · 6.2 KB

AGENTS.md

File metadata and controls

172 lines (123 loc) · 6.2 KB

AGENTS.md

Repository Overview

This is a personal NixOS configuration repository managed as a flake, with multiple user profiles and desktop environments. The configuration uses home-manager for user-level management and is structured modularly for maintainability.

Architecture

Configuration System

Multi-User Setup: The repository supports three user profiles defined in config-specifications.nix:

  • pro: Work profile (flo-pro) with Clever Cloud-specific tools
  • perso: Personal profile (flo-perso)
  • perso-workstation: Personal workstation with gaming support

Desktop Environments: Configurations support multiple desktop environments (Plasma, GNOME, Cosmic, Niri) via modules/desktop-env/, with the current focus on Niri (scrollable-tiling Wayland compositor).

Module Structure: The modules/ directory contains:

  • default.nix: Entry point importing all module categories
  • hardware/: Hardware-specific configurations per machine
  • system-config/: System-wide settings (boot, networking, i18n, sound, virtualization)
  • user/: User account and home-manager configuration
  • desktop-env/: Desktop environment configurations
  • packages/: Application and tool configurations
  • dev-env.nix: Development environment services
  • security.nix: Security and GPG settings
  • secrets.nix: Encrypted secrets (do not modify directly)

Configuration Pattern: User-specific settings use the currentUser special arg to dynamically adapt configurations. Desktop environments are conditionally imported via currentDesktop.

Package Management

Package configurations in modules/packages/ follow a pattern:

  1. Enable the program via home-manager
  2. Link dotfiles from dotfiles/ directory using mkOutOfStoreSymlink for mutable configs
  3. Define extra packages needed by the tool

Common packages are defined in modules/packages/default.nix with user-specific overlays (e.g., proPackages for work tools).

Dotfiles

The dotfiles/ directory contains actual configuration files for applications. These are symlinked into the user's home directory, allowing editing without rebuilding the system. Changes to these files take effect immediately or on application restart.

Common Commands

System Management

Rebuild system (applies changes from this repository):

# For the 'pro' profile
rebuild-pro

# For other profiles
rebuild-perso
rebuild-perso-workstation

# Manual rebuild (if aliases aren't available)
run0 nixos-rebuild switch --flake '/path/to/nixos-config#pro'

Update flake inputs and rebuild:

upd-pro  # Updates and rebuilds pro profile
upd-perso
upd-perso-workstation

# Manual approach
nix flake update --flake ~/.config/nixos-config

Clean old generations:

clean  # System and user garbage collection (>7 days old)

# Manual approach
run0 nix-collect-garbage --delete-older-than 7d
nix-collect-garbage --delete-older-than 7d

Development Workflow

Navigate to config:

nxcfg  # Alias for cd ~/.config/nixos-config

Check flake structure:

nix flake show
nix flake metadata

Test configuration without applying:

nixos-rebuild dry-build --flake ~/.config/nixos-config#pro

Format Nix files:

nixfmt **/*.nix

Making Changes

Adding a New Package

  1. System-wide package: Add to modules/packages/default.nix in commonPackages or user-specific list
  2. Package with configuration: Create modules/packages/package-name.nix, add it to imports in modules/packages/default.nix, and optionally add dotfiles to dotfiles/package-name/
  3. Rebuild system to apply changes

Modifying Application Config

For applications with dotfiles in dotfiles/ (Helix, Neovim, Zed, etc.):

  • Edit the files directly in dotfiles/
  • Changes take effect immediately or on app restart (no rebuild needed)

For applications configured via Nix modules:

  • Edit the corresponding .nix file in modules/packages/
  • Run rebuild-<profile> to apply

Adding a Desktop Environment

  1. Create modules/desktop-env/desktop-name.nix
  2. Add the desktop to config-specifications.nix in desktops
  3. Import conditionally in modules/desktop-env/default.nix
  4. Update flake.nix to create a configuration with the new desktop

Working with Secrets

Secrets are managed in modules/secrets.nix. Do not edit this file directly. Use appropriate secret management tools (likely sops-nix based on the sops package being installed).

Key Conventions

Nix Language Patterns

  • User-specific behavior: Use currentUser.name == specs.users.pro.name checks with lib.mkIf
  • Conditional imports: Use lib.optional or lib.optionals for dynamic module loading
  • Shell aliases: Defined in modules/user/shell-aliases.nix using the home directory as a base
  • Symlinks for mutable configs: Use config.lib.file.mkOutOfStoreSymlink to link dotfiles

File Organization

  • One module per .nix file with clear naming
  • Dotfiles mirror application config structure
  • Use default.nix as aggregation points that import other modules
  • Keep hardware-specific configs in modules/hardware/

Git Workflow

  • GPG signing is enabled for all commits (per-user keys in config-specifications.nix)
  • Default branch is main
  • Commits use histogram diff algorithm
  • Difftool and mergetool are configured to use nvim -c DiffviewOpen

Editor and Tools

Primary Editors: Zed (default for most file types), Neovim (terminal), Helix Terminal: Kitty (primary), with Ghostty and Warp also configured Shell: Fish (default), with Zsh, Nushell available Version Control: Git with Jujutsu (jj) also configured AI Tools: GitHub Copilot CLI, Claude Code, and Warp integrated

Zed has specialized rules in dotfiles/zed/rules/ for different interaction modes (ask, coding, debug) and project-level rules in .rules.

Important Notes

  • This configuration targets x86_64-linux
  • NixOS state version: 23.11 (do not change without reading documentation)
  • French keyboard layout (AZERTY) is configured
  • Wayland is the primary display protocol (NIXOS_OZONE_WL = "1")
  • Auto-upgrade is disabled; updates are manual via upd- aliases
  • Gaming support is conditionally enabled for perso-workstation profile