1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206# Nix Configuration for macOS
Personal Nix configuration for macOS using [nix-darwin](https://github.com/nix-darwin/nix-darwin) and [home-manager](https://github.com/nix-community/home-manager).
An interactive, VS Code-flavoured walkthrough of this repository is published at
**[naitokosuke-dotfiles.void.app](https://naitokosuke-dotfiles.void.app/)** (source in [`docs/`](docs/)).
## Prerequisites
- macOS on Apple Silicon
- [Lix](https://lix.systems/) package manager
- Xcode Command Line Tools (required for Homebrew)
## Installation
1. Install Xcode Command Line Tools:
```bash
xcode-select --install
```
2. Install Lix:
```bash
curl --proto '=https' --tlsv1.2 -sSf -L https://install.lix.systems/lix | sh -s -- install
```
3. Clone this repository:
```bash
git clone https://github.com/naitokosuke/dotfiles.git
cd dotfiles
```
4. Apply the configuration:
```bash
sudo nix run nix-darwin --extra-experimental-features "nix-command flakes" -- switch --flake .#Mac-big
```
## First-Time Setup on a New Machine
Activation builds everything this repository declares, and nothing below. Until these steps are
done the machine looks healthy: the very first `git commit` is what fails, because
[`home/git.nix`](home/git.nix) signs every commit and tag with `~/.ssh/id_ed25519.pub` and nothing
here creates that key.
Run them after the Installation switch above — `gh` and `playwright-cli` come from the
configuration — and in this order.
* Generate the key pair that [`home/ssh.nix`](home/ssh.nix) uses as the GitHub identity and
`home/git.nix` signs with. Keep the default path (`~/.ssh/id_ed25519`); `UseKeychain` stores the
passphrase in the macOS Keychain on first use.
```bash
ssh-keygen -t ed25519 -C "kosuke.naito.engineer@gmail.com"
```
* Log in to GitHub and register the public key twice — as an authentication key to push, and as a
signing key so GitHub reports the signatures as verified rather than the commits as unsigned.
Adding keys needs scopes beyond the default login.
```bash
gh auth login
gh auth refresh -h github.com -s admin:public_key -s admin:ssh_signing_key
gh ssh-key add ~/.ssh/id_ed25519.pub --type authentication --title "$(hostname -s)"
gh ssh-key add ~/.ssh/id_ed25519.pub --type signing --title "$(hostname -s)"
```
* Install the Playwright browsers. They are runtime-managed on purpose, so no closure contains
them and a fresh machine has none — see [`home/playwright.nix`](home/playwright.nix) for where
they land.
```bash
playwright-cli install-browser chromium
```
### Secrets
Nothing in this repository is encrypted and no secrets framework (`sops-nix`, `agenix`) is in the
flake. That is a decision rather than an omission: the SSH key above and the Keychain cover
everything this setup needs, and machine-local or private SSH host definitions are deliberately
kept out of the repository — `home/ssh.nix` includes them from `~/.ssh/config.d/` instead.
A framework would not remove the manual step either. An age key derived from the SSH key inherits
the ordering problem above: the key that decrypts the secrets is the same key the bootstrap has to
create by hand first. Worth revisiting when there is a secret that actually wants to live in here.
## Configuration Structure
```
.
├── flake.nix # Entry point: flake inputs and darwinConfigurations
├── nvfetcher.toml # Version tracker for CLI tools not in nixpkgs (nvfetcher)
├── pkgs/ # Custom package derivations (cclens, frog, gh-sub-issue, playwright-cli, vite-plus)
│ └── _sources/ # nvfetcher-generated pins (version + URL + hash) — never edit by hand
├── modules/
│ └── naitokosuke/ # Shared module: personal constants (username, email, …)
│ # exposed as `config.naitokosuke.*` to both nix-darwin and home-manager
├── hosts/ # System-level macOS settings (nix-darwin)
│ ├── common/ # Shared settings — Dock, Finder, keyboard, Homebrew,
│ │ # packages, Nix daemon, and home-manager wiring
│ ├── Mac-big/ # Mac mini host
│ └── Macbook-heavy/ # MacBook host (Touch ID for sudo)
├── home/ # User-level settings (home-manager), one module per program
│ ├── zsh.nix # Shell: PATH, environment variables, aliases
│ ├── git.nix # Git
│ ├── claude.nix # Claude Code settings, rules, skills
│ ├── ghostty.nix # Terminal
│ ├── starship.nix # Prompt
│ ├── claude-* # Claude Code deletion guard hook and Seatbelt sandbox
│ └── … # adrafinil, atuin, direnv, gh, gomi, gwq, mcp, nh, ssh, vite-plus, vscode, zoxide
└── docs/ # Interactive walkthrough web app (Vite+ / void)
# deployed to https://naitokosuke-dotfiles.void.app/
```
Each `default.nix` aggregates the modules in its directory — see them for the full list.
### CLI Packages
Managed via nixpkgs. See [`hosts/common/packages.nix`](hosts/common/packages.nix).
Tools not available in nixpkgs ([`frog`](https://github.com/wevm/frog),
[`gh-sub-issue`](https://github.com/yahsan2/gh-sub-issue),
[`vite-plus`](https://github.com/voidzero-dev/vite-plus) (`vp`),
[`playwright-cli`](https://github.com/microsoft/playwright-cli))
are packaged in [`pkgs/`](pkgs/) and reached as `pkgs.naitokosuke.<name>`, so they never shadow a nixpkgs attribute,
with versions and hashes tracked by [nvfetcher](https://github.com/berberman/nvfetcher) via
[`nvfetcher.toml`](nvfetcher.toml). A daily GitHub Actions workflow (08:00 JST) regenerates the pins and opens an update PR.
It skips releases younger than three days; run it by hand with `skip-cooldown` for an urgent fix.
vite-plus is the one package with a second half: `vp` is only a launcher, and the JavaScript toolchain
it delegates to is built from [`pkgs/vite-plus-runtime/`](pkgs/vite-plus-runtime/) and installed
alongside it. The two must stay on the same version, so the derivation refuses to build if the
lockfile and the nvfetcher pin disagree, and the nvfetcher workflow regenerates the lockfile as part
of the same PR. The approach follows [nix-vite-plus](https://github.com/ryoppippi/nix-vite-plus).
Once the official nixpkgs packaging of vite-plus ([NixOS/nixpkgs#533925](https://github.com/NixOS/nixpkgs/pull/533925))
lands, `pkgs/vite-plus.nix` will be replaced by `pkgs.vite-plus` (see the TODO in that file).
### GUI Apps
Managed via Homebrew Casks: GUI apps are casks, and CLIs come from Nix. See
[`hosts/common/homebrew.nix`](hosts/common/homebrew.nix).
### Hosts
The flake builds one `darwinConfiguration` per host listed in [`flake.nix`](flake.nix):
| Host | Machine |
| --------------- | ----------- |
| `Mac-big` | Mac mini |
| `Macbook-heavy` | MacBook |
## Customization
1. Update `hosts/common/packages.nix`: Add or remove CLI packages
2. Update `hosts/common/`: Add or modify system settings
3. Update `home/`: Add or modify user (home-manager) configurations
4. Update `modules/naitokosuke/`: Change personal constants (username, email, …)
## Usage
Apply configuration changes:
```bash
nh darwin switch
```
`nh` picks the host from the hostname, shows nix-output-monitor progress and a closure diff before
activating. `sudo darwin-rebuild switch --flake .#Mac-big` is the plain equivalent.
Update flake inputs:
```bash
nix flake update
nh darwin switch
```
Update nvfetcher-tracked tool versions (regenerates `pkgs/_sources/`):
```bash
nix run --inputs-from . nixpkgs#nvfetcher -- -o pkgs/_sources
```
## VSCode Settings Sync
VSCode settings are automatically synchronized from the [vscode-settings](https://github.com/naitokosuke/vscode-settings) repository
- Settings and keybindings are managed through Home Manager
- Existing settings are automatically backed up with `.backup` extension
- JSONC keybindings are converted to JSON format automatically
- Changes to the settings repository are applied with `nix flake update vscode-settings` and a rebuild
## Walkthrough Site (`docs/`)
[`docs/`](docs/) is a [Vite+](https://viteplus.dev/) / [void](https://void.app/) single-page app that renders this
repository as an interactive, VS Code-flavoured walkthrough. It reads the actual `*.nix` files, `nvfetcher.toml`, the
GitHub workflows, and this README at build time, so the published site always mirrors the real configuration.
Each file's walkthrough is its own comments: the leading comment is the intro, and a `## <title>` comment opens a
section about the code right below it. Facts such as installed casks, package versions and locked inputs are not
written down anywhere; they come from `nix eval --json .#docsData` ([`docs/facts.nix`](docs/facts.nix)).
```bash
cd docs
vp install # install dependencies
vp run facts # evaluate the facts the pages show (build and deploy do this first)
vp dev # local dev server
vp build # production build
vp check # format, lint, and type-check
```
It is deployed to <https://naitokosuke-dotfiles.void.app/> on every push to `main` by
[`.github/workflows/deploy-docs.yml`](.github/workflows/deploy-docs.yml), which authenticates through GitHub OIDC
and needs no stored secret. `vp run deploy` deploys by hand.