session-uuid

kokatsu's dotfiles

Dotfiles repository for managing shell and tool configurations across macOS and Linux systems using Nix + Home Manager with Flakes.

Features

• 🔄 Declarative & Reproducible - All configurations managed through Nix Flakes
• 🖥️ Multi-platform - Supports Linux (x86_64, aarch64) and macOS ARM (Apple Silicon)
• 📦 Unified Package Management - All CLI tools installed via Home Manager
• 🔗 Automated Symlinks - Dotfiles automatically linked to ~/.config/

Setup

Prerequisites

• macOS (arm64) or Linux (x86_64 / aarch64)
• curl (for Nix installer)

Installation

# Install Nix (using Determinate Systems installer)
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

# Clone the repository
git clone https://github.com/kokatsu/dotfiles.git ~/dotfiles
cd ~/dotfiles

# Build and activate Home Manager configuration
DOTFILES_DIR="$PWD" nix run home-manager -- switch --flake . --impure

Usage

Apply Configuration Changes

# User environment (packages / dotfiles) on both Linux and macOS.
# Set this to the actual repository path on each PC.
DOTFILES_DIR="$HOME/dotfiles" home-manager switch --flake "$HOME/dotfiles" --impure

# macOS system settings + Homebrew (quit Chrome first: casks get upgraded in place)
sudo HOSTNAME=$(hostname -s) DOTFILES_DIR="$HOME/dotfiles" darwin-rebuild switch --flake "$HOME/dotfiles" --impure

Update Packages

nix flake update
deno run --allow-all scripts/update-deno-deps.ts --all
DOTFILES_DIR="$HOME/dotfiles" home-manager switch --flake "$HOME/dotfiles" --impure

Development

nix develop        # Enter development shell with every linter / formatter
just check         # Format check, lint, typos, script tests, and flake evaluation
just fmt           # Format everything (Nix, Lua, shell, TOML, YAML, JSON, TypeScript)
just               # List all recipes

Lefthook runs a subset of these on commit and push (formatters, linters, gitleaks, commitlint); the script tests and flake evaluation only run through just check and CI.

Directory Structure

.
├── flake.nix          # Flake outputs and Home Manager/nix-darwin builders
├── flake.lock         # Locked dependencies for reproducibility
├── justfile           # Task runner: checks, formatters, tests
├── nix/
│   ├── home/          # Home Manager modules (packages, files, programs, services)
│   ├── darwin/        # macOS system and Homebrew configuration
│   └── overlays/      # Custom packages and upstream workarounds
├── bin/               # User scripts, linked to ~/.local/bin/scripts and on PATH
├── scripts/           # Test and helper scripts used by just and CI
├── karabiner-config/  # Karabiner-Elements rules written with karabiner.ts
└── .config/           # Dotfile sources linked by Home Manager
    ├── zsh/           # Zsh shell configuration
    ├── nvim/          # Neovim configuration
    ├── wezterm/       # WezTerm terminal configuration
    ├── claude/        # Claude Code settings, hooks, and skills
    └── ...            # Other tool configurations

Static application settings live in nix/home/programs/. Home Manager generates Git, Ghostty, ripgrep, Starship, Yazi, Biome, markdown-oxide, ov, Taplo, psql, Vim, Claude Code keybindings, and the Codex base configuration from Nix. Edit these modules, then run home-manager switch --flake . --impure to apply them.

Yazi plugins come from nixpkgs yaziPlugins where available; the remaining plugins and flavors are vendored under .config/yazi/. All are installed through programs.yazi; update them via nix flake update or in Git instead of using ya pkg. Yazi's init.lua and git-changes.sh also need home-manager switch --flake . --impure after editing to apply the changes. Lua, shell scripts, and repository tooling configurations remain under .config/.

Neovim's lazy.nvim, peek.nvim, blink.cmp, Pkl plugin, and Tree-sitter parsers are built by Nix and linked under ~/.local/share/nvim/nix-plugins/. Other Lua plugins still use lazy-lock.json and :Lazy. zeno.zsh uses fixed Deno/npm dependencies from the Nix store. Ruby LSP and its Rails/RuboCop gems are fixed in nix/ruby/ruby-lsp/; Neovim uses RUBY_LSP_COMMAND to avoid a user-installed gem taking precedence. Karabiner's managed Default profile is built by Nix, then merged into the writable JSON while retaining other profiles and GUI settings.

Renovate PRs regenerate Deno locks/hashes and Ruby gemsets in pr.yml.

Claude Code's settings.json keeps its writable repository link. Codex receives a writable copy of its generated configuration and preserves the existing local state sections during activation.

License

MIT. Third-party notices are listed in THIRD_PARTY_LICENSES.md.