⚙️ seroperson's dotfiles

Configuration which I use for my daily development purposes.

✨ Features

• Installation and building is fully managed by nix.
• Powered by zimfw/zimfw plugin manager (see zsh/.zimrc for all used plugins) lightweight zsh shell.
• zimfw/minimal theme.
• rupa/z to jump around most used directories (mapped to j command).
• Automatically starts herdr (or tmux, selected by the multiplexer flake flag).
• Automatically inits gpg and ssh-agent sessions.
• Store sensitive settings under untracked zsh/machine-based.zsh file.
• Comes with many development utils, like eza, rg, jq, yq, ouch (see home.nix for complete list).
• nix-community/comma to run software without installation (like , tree to download and run tree).
• Customized AstroNvim community distribution.

Some overview is also available in my article ⚙️ Managing dotfiles with Nix.

📲 Preview without installation

To try this configuration, you can either start it in Docker container or using nix develop shell:

Docker

nix build github:seroperson/dotfiles#docker
docker load < ./result
docker run --rm -it seroperson.me/dotfiles

nix develop

You'll also need to redefine your HOME and USER environment variables:

mkdir -p /tmp/test
USER=seroperson-preview HOME=/tmp/test nix develop --impure github:seroperson/dotfiles

🚀 Installation

Initially, only nix and git must be installed. Be sure that nix is up-to-date:

nix-channel --add https://nixos.org/channels/nixpkgs-unstable
nix-channel --update

Clone the repository:

git clone https://github.com/seroperson/dotfiles $HOME/.dotfiles/

And then let the home-manager do the rest:

home-manager init --switch $HOME/.dotfiles/ --flake $HOME/.dotfiles/

or using nix, if home-manager is unavailable:

export NIX_CONFIG="extra-experimental-features = nix-command flakes"
nix run github:nix-community/home-manager -- init --switch $HOME/.dotfiles/ --flake $HOME/.dotfiles/

macOS (Apple Silicon): the commands above resolve to the Linux configuration. On macOS, target the darwin home configuration explicitly:

home-manager switch --flake $HOME/.dotfiles#seroperson@darwin

or, if home-manager is unavailable:

export NIX_CONFIG="extra-experimental-features = nix-command flakes"
nix run github:nix-community/home-manager -- switch --flake $HOME/.dotfiles#seroperson@darwin

Next, you should do chsh $USER -s $HOME/.nix-profile/bin/zsh and re-login. On macOS the shell must be listed in /etc/shells before chsh will accept it:

echo "$HOME/.nix-profile/bin/zsh" | sudo tee -a /etc/shells
chsh -s "$HOME/.nix-profile/bin/zsh"

Finally, be sure to install Nerd Font and Catpuccin theme (mocha variant) for your terminal.

📦 Update packages

In order to update installed packages, use the following commands:

nix-channel --update
nix-env -u --always
nix flake update

And then re-init home-manager with command from section above.

Alternatively, to bump just the flake inputs and rebuild in a single step (run from the repo root):

nix flake update && home-manager init --switch . --flake .

🚦 Troubleshooting

Usually nix doesn't work as expected and you don't know what to do. It is good idea to start your troubleshooting with global cleanup:

nix-channel --update
nix-env -u --always
rm /nix/var/nix/gcroots/auto/*
rm -rf $HOME/.cache/nix
nix-collect-garbage -d

Also it's possible to debug nix variables using nix repl. For example, to load flake into repl, you can do the following:

nix repl

nix-repl> :lf ./
nix-repl> builtins.attrNames homeConfigurations.seroperson

🧠 Agent skills

Claude Code, pi and zcode share one skill set through ~/.claude/skills. The skills themselves are not vendored here - they come from nextlevelbuilder/ui-ux-pro-max-skill, pinned as a source-only flake input and linked per skill by nix/claude-skills.nix:

• to enable or disable one, edit the enabled list in that file
• to move to a newer upstream: nix flake update ui-ux-pro-max, then just switch-linux
• to roll a bad bump back: revert flake.lock and switch again

Hand-written skills can live next to them: ~/.claude/skills is a real directory, only its upstream entries are store symlinks.

🩹 Local patches

Some installed tools patch themselves outside of home-manager's control: pi materializes its extension tree (~/.pi/agent/npm/node_modules) on its own, so any fix applied there is wiped by every pi update / pi install. Such fixes live in pi/patches/ as <package>--<description>.patch files and are re-applied automatically:

• on every home-manager switch (see applyPiPatches in home.nix)
• right after pi update / pi install (the ~/.local/share/bin/pi wrapper)

To add a patch: drop a <package>--<description>.patch into pi/patches/ (git add it - the flake only sees tracked files). A version bump that shifts the patched source fails the dry-run and warns on the next switch, so the patch can be rebased.

📂 Nix Guides

nix is not easy thing to get started with, but luckily it has a lot of guides available across the web. Here are some of them:

• Scrive Nix Workshop
• Introduction to Flakes
• Packaging software with Nix
• Home Manager Configuration Options
• Home Manager modules/
• Shebang Scripts in Nix Derivations