forked from
lass.pds.lassul.us/superconfig
This repository has no description
CLAUDE.md: rename to AGENTS.md, add nix fmt pre-commit reminder
author
lassulus
date
(Feb 23, 2026, 12:23 AM CET)
commit
3fdd9edf
3fdd9edfa70f5ddeabbfd3d6812f06f4db346183
parent
b3eaee29
b3eaee290d7e9b2edd58e17b33b65a3e9b4a0fc6
+87
-83
+87
AGENTS.md
+87
AGENTS.md
···
1
+
# CLAUDE.md
2
+
3
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+
## Repository Overview
6
+
7
+
This is lassulus's personal NixOS/nix-darwin configuration repository, built on clan-core for managing multiple machines. It includes:
8
+
- Multiple machine configurations in `machines/`
9
+
- Configuration modules in `2configs/` and `3modules/`
10
+
- Custom packages in `5pkgs/`
11
+
- packages which could in theory be upstreamed to nixkgs should go into the pkgs folder, in the tools folder we add tools we write ourself which are more complex or not upstreamable
12
+
13
+
## Key Architecture Components
14
+
15
+
### Machine Management
16
+
- **Clan-core**: Primary framework for managing multiple machines
17
+
- **Secrets**: Uses password-store for secrets management via clan.core.vars
18
+
19
+
### Network Overlays
20
+
The repository manages multiple overlay networks:
21
+
- **Tor**: Anonymous network access
22
+
23
+
### Module System
24
+
- `2configs/`: Main configuration modules
25
+
- `2configs/default.nix`: imported by all machines
26
+
- `3modules/`: Custom NixOS module definitions
27
+
- Stockholm modules are also imported for krebs infrastructure
28
+
29
+
## Common Development Commands
30
+
31
+
```bash
32
+
# Enter development shell
33
+
nix develop
34
+
35
+
# Deploy to a specific machine
36
+
clan machines update <MACHINE_NAME>
37
+
38
+
# Format code
39
+
nix fmt
40
+
41
+
# Build NixOS configuration
42
+
nix build .#nixosConfigurations.<machine-name>.config.system.build.toplevel
43
+
44
+
# Build Darwin configuration
45
+
nix build .#darwinConfigurations.barnacle.system
46
+
47
+
# Deploy/rebuild Darwin configuration (for barnacle)
48
+
sudo darwin-rebuild switch --flake .#barnacle
49
+
50
+
# Access machines via SSH
51
+
ssh <machine-name>.r # via retiolum
52
+
ssh <machine-name>.s # via spora
53
+
ssh <machine-name>.n # via nether
54
+
torify ssh $(pass show machines/<machine-name>/tor-hostname) # via tor
55
+
```
56
+
57
+
## Important: Git Staging for Flake Evaluation
58
+
59
+
**CRITICAL**: New nix files must be staged (git add) before they are available in flake evaluation. When creating new packages, modules, or any nix files, always run `git add <files>` before testing with `nix build`, `nix run`, etc.
60
+
61
+
## Machine Facts and Secrets via vars
62
+
63
+
- SSH public keys
64
+
- Network identities (retiolum, mycelium, zerotier)
65
+
- Syncthing IDs
66
+
- DKIM keys (for mail servers)
67
+
68
+
Secrets are managed via password-store and uploaded to `/run/secrets` on deployment.
69
+
70
+
## Adding New Machines
71
+
72
+
1. Create directory `machines/<name>/`
73
+
2. Add `config.nix`, `physical.nix`, and optionally `disk.nix`
74
+
3. Generate facts using clan-cli
75
+
4. Add to inventory in `flake.nix`
76
+
5. Deploy using `nix run .#deploy -- <name>`
77
+
78
+
## Pre-Commit
79
+
80
+
**CRITICAL**: Always run `nix fmt` before committing to ensure all files pass the treefmt formatting check in CI.
81
+
82
+
## Commit Message Guidelines
83
+
84
+
- Use simple, descriptive commit messages without attribution footers
85
+
- Use flake attribute paths as prefixes (e.g., `tools.mutt:` not just `mutt:`)
86
+
- For flake.lock updates, use: "flake.lock: update"
87
+
- Follow existing patterns seen in git log
-83
CLAUDE.md
-83
CLAUDE.md
···
1
-
# CLAUDE.md
2
-
3
-
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
-
5
-
## Repository Overview
6
-
7
-
This is lassulus's personal NixOS/nix-darwin configuration repository, built on clan-core for managing multiple machines. It includes:
8
-
- Multiple machine configurations in `machines/`
9
-
- Configuration modules in `2configs/` and `3modules/`
10
-
- Custom packages in `5pkgs/`
11
-
- packages which could in theory be upstreamed to nixkgs should go into the pkgs folder, in the tools folder we add tools we write ourself which are more complex or not upstreamable
12
-
13
-
## Key Architecture Components
14
-
15
-
### Machine Management
16
-
- **Clan-core**: Primary framework for managing multiple machines
17
-
- **Secrets**: Uses password-store for secrets management via clan.core.vars
18
-
19
-
### Network Overlays
20
-
The repository manages multiple overlay networks:
21
-
- **Tor**: Anonymous network access
22
-
23
-
### Module System
24
-
- `2configs/`: Main configuration modules
25
-
- `2configs/default.nix`: imported by all machines
26
-
- `3modules/`: Custom NixOS module definitions
27
-
- Stockholm modules are also imported for krebs infrastructure
28
-
29
-
## Common Development Commands
30
-
31
-
```bash
32
-
# Enter development shell
33
-
nix develop
34
-
35
-
# Deploy to a specific machine
36
-
clan machines update <MACHINE_NAME>
37
-
38
-
# Format code
39
-
nix fmt
40
-
41
-
# Build NixOS configuration
42
-
nix build .#nixosConfigurations.<machine-name>.config.system.build.toplevel
43
-
44
-
# Build Darwin configuration
45
-
nix build .#darwinConfigurations.barnacle.system
46
-
47
-
# Deploy/rebuild Darwin configuration (for barnacle)
48
-
sudo darwin-rebuild switch --flake .#barnacle
49
-
50
-
# Access machines via SSH
51
-
ssh <machine-name>.r # via retiolum
52
-
ssh <machine-name>.s # via spora
53
-
ssh <machine-name>.n # via nether
54
-
torify ssh $(pass show machines/<machine-name>/tor-hostname) # via tor
55
-
```
56
-
57
-
## Important: Git Staging for Flake Evaluation
58
-
59
-
**CRITICAL**: New nix files must be staged (git add) before they are available in flake evaluation. When creating new packages, modules, or any nix files, always run `git add <files>` before testing with `nix build`, `nix run`, etc.
60
-
61
-
## Machine Facts and Secrets via vars
62
-
63
-
- SSH public keys
64
-
- Network identities (retiolum, mycelium, zerotier)
65
-
- Syncthing IDs
66
-
- DKIM keys (for mail servers)
67
-
68
-
Secrets are managed via password-store and uploaded to `/run/secrets` on deployment.
69
-
70
-
## Adding New Machines
71
-
72
-
1. Create directory `machines/<name>/`
73
-
2. Add `config.nix`, `physical.nix`, and optionally `disk.nix`
74
-
3. Generate facts using clan-cli
75
-
4. Add to inventory in `flake.nix`
76
-
5. Deploy using `nix run .#deploy -- <name>`
77
-
78
-
## Commit Message Guidelines
79
-
80
-
- Use simple, descriptive commit messages without attribution footers
81
-
- Use flake attribute paths as prefixes (e.g., `tools.mutt:` not just `mutt:`)
82
-
- For flake.lock updates, use: "flake.lock: update"
83
-
- Follow existing patterns seen in git log