dotfiles

# dotfiles

[![DeepWiki](https://img.shields.io/badge/DeepWiki-ryoppippi%2Fdotfiles-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/ryoppippi/dotfiles)

<!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->

ryoppippi's dotfiles, managed as a Nix flake: nix-darwin plus Home Manager on macOS, standalone Home Manager on Linux.

## Layout

- `flake.nix` — inputs only; the outputs are flake-parts modules under `nix/flake/`
- `nix/flake/` — flake-parts modules: `apps/`, `hosts/`, `formatter.nix`, `pkgs.nix`
- `nix/mk-pkgs.nix` — the overlaid nixpkgs instance shared by `perSystem` and the hosts
- `nix/modules/home/` — cross-platform Home Manager modules (packages, programs, dotfile symlinks)
- `nix/modules/darwin/` — macOS system settings, Homebrew, OmniWM
- `nix/modules/linux/` — Linux-only modules
- `nix/overlays/` — custom packages, also exposed as flake `packages`
- `nix/packages/node/` — Node packages built with Nix
- `fish/`, `nvim/`, `karabiner/` — plain config, symlinked or generated into place by Home Manager
- `agents/AGENTS.md`, `agents/shared/`, `agents/skills/` — global instructions, their fragments, and skills shared by Claude Code and Codex
- `registry/sources/` — pinned external skill repositories

## Setup

Installing Nix is the one manual step, because everything after it is a Nix
command. Pick the installer for the platform:

```sh
# macOS
curl -sSfL https://artifacts.nixos.org/nix-installer | sh -s -- install --enable-flakes

# Linux
curl --proto '=https' --tlsv1.2 -sSf -L https://install.nixos.org | sh -s -- install
```

Then one command does the rest, on both platforms:

```sh
nix run --accept-flake-config github:ryoppippi/dotfiles
```

It fetches this repository with `ghq` into `~/ghq/github.com/ryoppippi/dotfiles`
— the path the modules symlink the live fish, zsh and Neovim configuration out
of, and the ghq root the configuration goes on to set — then runs that
checkout's own `nix run .#switch`, so everything is applied from a tree that can
be edited afterwards rather than from the store. On macOS it first offers to
open the App Store, since `masApps` needs an account signed in, and accepts the
Xcode licence when full Xcode is present. On Linux there is nothing to do before
the switch, which runs Home Manager as the user.

`--accept-flake-config` is what lets the binary caches in `nixConfig` be used
without a prompt for each one.

Afterwards, `exec fish` picks up the new shell.

### Applying later changes

From inside the checkout:

```sh
git add <changed paths> && nix run .#switch
```

Nix flakes only see tracked, staged files, so stage what changed before
switching.

### GitHub API rate limit

If Nix hits the GitHub API rate limit, load a token into `GITHUB_TOKEN` from a
credential helper or password manager, then retry. Never paste the token into
the command line or commit it.

```sh
NIX_CONFIG="access-tokens = github.com=$GITHUB_TOKEN" \
  nix --accept-flake-config run .#switch
```

## Daily Usage

Flakes only see tracked, staged files, so `git add` changed paths before switching.

| Command                          | What it does                                                      |
| -------------------------------- | ----------------------------------------------------------------- |
| `nix run .#switch`               | Build and apply the darwin (macOS) or Home Manager (Linux) config |
| `nix run .#build`                | Build without applying                                            |
| `nix run .#fmt`                  | Run treefmt (`-- --fail-on-change` is what CI runs)               |
| `nix run .#update`               | Update every flake input                                          |
| `nix run .#update-ai-tools`      | Update only the `llm-ag

... (truncated)