dotfiles
One repo for the whole machine: a Nix-declared macOS setup (nix-darwin + home-manager flake, Homebrew for casks, a one-shot bootstrap) and portable AI coding-harness configs — shared skills, commands, rules, agents, and settings — provisioned from one source of truth across multiple Claude Code profiles, pi, Devin CLI, and GitHub Copilot CLI.
A personal repo, published so others can borrow the architecture.
Paths are hardcoded to one machine — adapt before adopting (see Adopt it).
New Mac quick start
curl -fsSL https://raw.githubusercontent.com/sanketsudake/dotfiles/main/bootstrap.sh -o /tmp/bootstrap.sh
bash /tmp/bootstrap.sh
The script is idempotent: Xcode CLT, Homebrew, and Determinate Nix if missing, clone to ~/personal/dotfiles, one darwin-rebuild switch (packages, dotfile links, macOS defaults; pre-existing files are moved to a timestamped ~/.dotfiles-backup-* dir), harness links, tools, and make doctor.
Afterwards run the printed manual steps (gh auth login, atuin login, git lfs install) and open a new terminal.
On an existing machine, clone the repo and run make install.
Omarchy (Arch Linux) quick start
curl -fsSL https://raw.githubusercontent.com/sanketsudake/dotfiles/main/bootstrap-omarchy.sh -o /tmp/bootstrap-omarchy.sh
bash /tmp/bootstrap-omarchy.sh
Same repo, same make install, different system layer — see Omarchy host.
Ideas worth stealing
- One source of truth, many harnesses.
A single
skills/ tree feeds Claude Code, pi, Devin CLI, and Copilot CLI; edit once, every harness sees it immediately.
Devin reads ~/.agents/skills and Copilot reads ~/.copilot/skills; both links point at the same tree, and the same agents/*.md files link into each CLI under the name it expects.
- Two Claude profiles via
CLAUDE_CONFIG_DIR.
pclaude / wclaude wrappers keep personal and work accounts isolated while sharing the same skills and rules.
- Per-resource source tracking.
Every skill and agent source lives in one
sources.toml manifest; vendored skills are pinned there (repo, subpath, commit) and materialized on install — so an upstream update is one command and a bare clone stays reproducible.
- Generated catalog, enforced by a doctor.
skills/README.md is generated from that metadata; make skills-doctor fails when anything drifts.
- Guardrails as code, not hope.
Extensions for pi confirm before destructive actions, block dirty-repo commits, and protect paths;
a
PreToolUse safety hook does the same for Claude Code (deny/ask on dangerous shell, secrets, and VCS internals);
plugins.txt declares the plugin set and make plugins-check reports drift per profile.
- Skills are scanned before they land.
make skills-scan runs NVIDIA SkillSpector over every skill, skills-fetch/skills-update refuse a skill that fails, and accepted findings carry a reason in skills/.security/skillspector/.
- Measured, not assumed.
make context-budget reports the always-loaded context per session (capped by the doctor), and a SubagentStop/Stop telemetry hook plus make usage-report show spend by agent type × model and cache-hit ratio.
CI runs the doctor, catalog, script tests, and the security scan on every push.
Layout
dotfiles/
├── Makefile # primary interface — every <resource>-<action> target
├── CLAUDE.md # guide for agents working IN this repo (full Makefile reference)
├── bootstrap.sh # new-Mac entry point
├── flake.nix # nix entry point; flake.lock pins nixpkgs/nix-darwin/home-manager
├── nix/ # darwin/ system config (defaults, homebrew) + home/ user env
├── manifests/ # non-brew tools: go-tools.txt, npm-globals.txt, pipx-tools.txt
├── macos/ # deliberately-changed macOS defaults (make macos-apply)
├── packages/ # dotfile sources for $HOME (zsh, git, atuin, btop, gh, bin), linked by home-manager
│ ├── agents/ # AGENTS.md — global rules shared by Devin CLI + Copilot CLI
│ ├── devin/ # Devin CLI config.json
│ └── copilot/ # Copilot CLI settings.json
├── claude/ # Claude Code config, symlinked into both profiles
│ ├── CLAUDE.md # shared global user instructions
│ ├── commands/ # slash commands
│ ├── agents/ # subagents
│ ├── rules/ # model routing, git hygiene, delegation
│ ├── scripts/ # hooks (routing, safety guard, usage telemetry) + statusline
│ └── plugins.txt # desired-state plugin list
├── skills/ # shared skills for Claude + pi — the source of truth
│ ├── README.md # generated catalog — start here
│ └── .security/ # SkillSpector baselines (accepted findings, with reasons)
├── suites/ # curated skill-suite landing pages
├── pi/ # pi agent config, linked into ~/.pi
└── scripts/ # repo tooling (doctor, drift, resource manager — not symlinked)
make install links skills/ and claude/* into both Claude profiles, pi/ into ~/.pi, and the shared skills, agents, and configs into Devin CLI and Copilot CLI (home-manager out-of-store symlinks) — safe to re-run.
Because everything is symlinked, one edit here applies to every profile and both harnesses at once.
What's inside
Skills — browse the catalog (grouped by category, generated from each skill's metadata).
Most are authored here; the rest are vendored from pi-skills, cursor-team-kit, anthropics/skills, and the skills.sh ecosystem — each linked to its upstream source at a pinned commit.
Suites — curated skill sets with their own landing pages:
- Go CI Health — Keep a Go repo’s CI green, fast, and secure
- Agent-Maintained Hugo Site — Write, illustrate, verify, optimize, and measure a Hugo blog with an agent
- OSS Maintainer Copilot — Backlog triage, CodeQL remediation, and security advisories for repos you maintain
- PR Shepherding — Get a pull request from pushed to merged: clean diff, green CI, resolved reviews
- Second Brain — An Obsidian knowledge base your agent maintains for you
Agents
| Agent | Purpose |
|---|
plan-reviewer | Pre-execution plan review against the actual codebase; APPROVE/REVISE with evidence. |
bulk-mechanic | Haiku executor for mechanical, judgment-free batches. |
pr-shepherd | Drives the push → CI → bot-review loop to green. |
skill-auditor | Audits a skill directory against this repo's conventions. |
Rules
| Rule | Governs |
|---|
model-routing.md | Cheapest reliable model tier per task, and effort calibration. |
git-hygiene.md | Staging, commit, and push discipline. |
delegation.md | When to hand work to the agents above instead of doing it inline. |
Plus the shared CLAUDE.md (secrets hygiene, semantic-line-break markdown per sembr.org), the /history command, helper scripts, and pi guardrail extensions vendored from pi-mono.
Adopt it
Prerequisites: git, jq (plus gh / python3 / npx for the skills that use them).
git clone https://github.com/sanketsudake/dotfiles.git
cd dotfiles
# Before installing:
# 1. Edit CLAUDE_CONFIG_DIRS in the Makefile (your profiles)
# 2. Copy the pclaude/wclaude snippets from scripts/claude-multi-account.sh into your shell profile
# 3. Make claude/CLAUDE.md yours — it's opinionated
# 4. Review nix/, manifests/, and packages/ — they describe one person's machine
make install # nix-switch (packages + dotfiles + defaults + harness links) + skills-materialize + tools
make skills-list # see each skill's source and status
make uninstall reverses it.
Working with it
Everyday targets — CLAUDE.md carries the full <resource>-<action> reference, and every skills-* target has an agents-* twin.
| Target | Does |
|---|
install / uninstall | Apply the declared system and links, or reverse it. |
skills-find / skills-add | Discover skills on skills.sh and vendor them. |
skills-catalog / skills-doctor | Regenerate the catalog / validate every skill and its freshness. |
skills-update[-all] | Re-fetch vendored skills whose upstream moved. |
plugins-check / plugins-sync | Report plugin drift per profile / emit the /plugin install lines. |
Two gotchas: vendored skills/ and packages/pi/extensions/ are overwritten on re-sync — diverge intentionally and note it durably; and use SUBPATH=, never PATH=, on fetch targets (the latter clobbers the shell PATH).
Plugin installation stays manual per profile — Claude Code has no headless /plugin install.
Plan review with Plannotator
Plannotator opens each Claude Code plan in Helium before Claude may leave plan mode.
It has three parts, pinned to the same release:
the binary (nix/home/plannotator.nix),
the plannotator@plannotator plugin that adds the ExitPlanMode hook (first run /plugin marketplace add backnotprop/plannotator),
and the vendored plannotator-review, plannotator-annotate, and plannotator-last skills.
The nix wrapper selects Helium, keeps the server on 127.0.0.1, and turns off share links and AI features;
set a PLANNOTATOR_* variable in the environment to override one.
The review loop:
- Claude runs
plan-reviewer, then calls ExitPlanMode; Helium opens the plan.
- Annotate — delete, comment, labels, global comments, or direct edits — then click Send Feedback.
- Claude revises and resubmits.
The
+N/-M badge shows the diff; the Version Browser compares any earlier version.
- Repeat.
Click Approve only when nothing needs action:
Approve drops unsent notes and sets the session permission mode (select
auto in the first-run dialog).
Also: /plannotator-review [PR URL] for code review, /plannotator-annotate <file> for a Markdown file, /plannotator-last for Claude's last reply, and plannotator archive for past decisions.
These three skills work in Claude Code only:
they use its !`command` injection, so pi, Devin, and Copilot see them as inert text.
Machine setup
| Target | Does |
|---|
install | nix-switch + harness links + tools-install |
nix-switch / nix-build | Apply the whole declared system / build-only preview |
nix-check / nix-fmt | Flake check + statix lint / format the nix files |
nix-update | Bump flake.lock; review the diff like a Brewfile re-curation |
nix-rollback | Switch back to the previous system generation |
tools-install | go-install + npm-install + pipx-install from manifests/ |
brew-check | Verify installed brew state against the nix-generated brewfile |
brew-dump | Regenerate gitignored Brewfile.dump to diff against nix/darwin/homebrew.nix |
cask-adopt | Take over apps installed outside brew (pkg casks prompt for sudo) |
macos-apply | Run macos/defaults.sh (Helium-only; system defaults live in nix) |
doctor | Run all health checks |
drift | Report divergence between recorded config and the live system, both directions |
raycast-export | Open Raycast's encrypted settings export; save the file privately (never committed) |
The nix model
The machine is declared once and applied with make nix-switch:
flake.nix pins nixpkgs, nix-darwin, and home-manager in flake.lock,
nix/darwin/ declares the system (macOS defaults, and every brew/cask/mas/vscode entry via the homebrew module),
and nix/home/ declares the user environment (dotfile links and CLI packages).
Dotfile sources stay in packages/ with their dot- names;
home-manager links each file individually into $HOME,
so ~/.config/<tool> stays a real directory and credential files written beside managed configs
(e.g. gh's hosts.yml) can never land in the repo — the old --no-folding invariant, kept.
Never declare files from credential-bearing dirs (gcloud, 1Password, op, github-copilot) or credential-bearing files (gh/hosts.yml, ~/.copilot/config.json).
Every switch is a numbered generation; make nix-rollback returns to the previous one.
Homebrew remains for casks/taps/mas (declared in nix/darwin/homebrew.nix, applied by the same switch,
cleanup = "uninstall": an undeclared install is removed on the next switch — promote keepers first).
Two rules with no exceptions:
flakes only see git-tracked files, so git add new .nix files before building;
and never let home-manager own a directory that holds mutable files.
Omarchy host
A Linux laptop running Omarchy is a homeConfigurations."<user>@<hostname>" entry (mkHomeHost in flake.nix, host module in nix/hosts/):
standalone home-manager on top of the distro, not NixOS and not a system module.
The split is deliberate:
- Nix (Determinate installer, as on the Mac) owns the user CLI set in
nix/home/packages.nix and every dotfile/harness link — the same modules the Mac uses. Mac-only packages sit behind pkgs.stdenv.hostPlatform.isDarwin; targets.genericLinux.enable supplies the non-NixOS session glue.
- pacman/yay and Omarchy own the kernel, drivers, Hyprland and the desktop, GUI apps, docker, and the login shell.
manifests/arch-packages.txt (make pacman-install) declares the few system packages this repo needs, starting with zsh.
- mise keeps Omarchy's
claude/codex/gh CLIs, but not Node.js: node comes from nix on both hosts, so run mise rm -g node after an Omarchy install (and after omarchy-install-dev-env, which adds it back); 05-omarchy.zsh activates it ahead of the nix profile and ports the rest of Omarchy's bash rc (env bootstrap, editor/browser exports, starship, eza aliases). The module is a no-op on macOS.
Omarchy-owned paths are never linked over: ~/.config/hypr and the desktop, ~/.config/git/config (Omarchy writes it; ~/.gitconfig wins), and btop.conf (its theme switcher repoints color_theme) — dotfiles.omarchy = true skips btop and the macOS-only bin/ helpers.
The exception is Omarchy's personal-override file ~/.config/hypr/input.lua (Num Lock off at login), linked per file into the store by nix/home/omarchy.nix (edits apply on make nix-switch), which also runs the lock-keys-osd user service: an Omarchy OSD whenever Caps Lock or Num Lock changes.
Omarchy also seeds ~/.agents/skills with its own skills, so there the skills are linked per skill (names from sources.toml, plus Omarchy's omarchy and diagnose-crash) into a directory that stays real; a newly fetched skill shows up after the next make nix-switch.
The Claude profiles are per host too (dotfiles.claudeProfiles); the laptop has only ~/.claude-personal, and plain claude goes straight to it.
make nix-switch runs the flake-pinned home-manager (switch -b hm-backup), make nix-build previews, and nix run .#home-manager -- generations lists what to roll back to.
CI evaluates every homeConfigurations entry alongside the darwin hosts.
Harness links
The harness targets (~/.claude-*, ~/.pi, ~/.agents, ~/.config/devin, ~/.copilot) are home-manager out-of-store symlinks into the repo working tree (nix/home/harness.nix) —
the linked content stays mutable, so vendored skills materialize in place and repo edits apply live.
~/.pi/agent, ~/.pi/extensions, and the Devin/Copilot agent dirs link per-file on purpose: those tools write state beside them,
and a whole-dir link would let a tool write into the repo.
Devin CLI reads personal skills from ~/.agents/skills; Copilot CLI 0.0.417 scans ~/.copilot/skills (plus ~/.claude/skills and the project dirs) and does not look at ~/.agents/skills yet.
Each CLI therefore gets its own link to the same skills/ tree — the paths never collide, so no skill is discovered twice.
The subagents in packages/claude/agents/ link into ~/.config/devin/agents/<name>.md and ~/.copilot/agents/<name>.agent.md — same file, two names.
Global always-on rules come from packages/agents/AGENTS.md, linked as ~/.config/devin/AGENTS.md and ~/.copilot/copilot-instructions.md.
Of each CLI's own config, only the user-editable file is managed (~/.config/devin/config.json, ~/.copilot/settings.json);
~/.copilot/config.json holds login state and the two herdr-agent-state.sh hook scripts are installed by herdr, so all three stay local files.
Verifying what each CLI actually loaded
make doctor checks that the links resolve into the repo; these commands check that the tools use them.
| Check | Devin CLI | Copilot CLI |
|---|
| Subagents | devin doctor — lists the loaded profiles and warns on unknown frontmatter keys | copilot --agent <name> -p 'reply OK' — the run header names the agent |
| Skills | devin skills list — each skill with its ~/personal/dotfiles/skills/... path | /skills list in an interactive session — it prints the dirs it scanned |
| Global rules | devin rules list — AGENTS [Standard] always-on | copilot -s -p '…answer from your instructions only…' — it answers from copilot-instructions.md |
| Own config | read at ~/.config/devin/config.json (--config overrides it) | /settings in an interactive session |
Copilot has no skill subcommand and no non-interactive readback,
so /skills list inside a session is the check that counts —
its "No skills found" message names the dirs it scanned, which is how the ~/.copilot/skills link was found to be necessary.
Do not trust the ~/.agents/skills path from the GitHub docs alone; the running binary is the authority.
For the rest, copilot --log-level debug --log-dir /tmp/cop -p 'hi' is the ground truth:
the log warns per agent file on an unknown frontmatter key (effort is Claude-only, and both CLIs ignore it),
and records that model: haiku maps to claude-haiku-4.5.
zsh keeps its drop-in idea: ~/.zshrc is a thin loader sourcing ~/.config/zsh/*.zsh in NN- prefix order,
and machine-local uncommitted overrides go in ~/.config/zsh/90-local.zsh
(a plain untracked file; see 90-local.zsh.example).
Adding a new tool config
mkdir -p packages/<tool>/dot-config/<tool> and copy the non-secret config file(s) in, using dot- names for anything dotted.- Add a
home.file entry for each file in a new nix/home/<tool>.nix, import it from nix/home/default.nix, and add <tool> to HM_PACKAGES in the Makefile (drives doctor's link checks).
git add the new files, make nix-switch, review, then commit.
Secrets policy
Nothing outside packages/ is ever linked into $HOME, and no package references a credential-bearing file.
.gitignore blocks secret-like filenames as a second layer, and make doctor fails on secret-pattern filenames, credential-looking content in tracked files, or a ~/.config dir that has become a symlink.
Nothing imports live machine files automatically any more; copy configs into packages/ by hand and review git diff before committing.
License
Apache-2.0.
Vendored skills and extensions remain under their upstream licenses; see each resource's source metadata.
