https://github.com/fnayou/dotfiles
Cross-platform (macOS + Arch) dotfiles managed with GNU Stow — zsh, git, Neovim, Alacritty, bat, eza, Herdr, Oh My Posh, Taskfile, Claude Code. Catppuccin Macchiato.
https://github.com/fnayou/dotfiles
alacritty arch-linux bat catppuccin claude-code dotfiles endeavouros eza git gnu-stow herdr macos neovim oh-my-posh shell task taskfile zsh
Last synced: about 13 hours ago
JSON representation
Cross-platform (macOS + Arch) dotfiles managed with GNU Stow — zsh, git, Neovim, Alacritty, bat, eza, Herdr, Oh My Posh, Taskfile, Claude Code. Catppuccin Macchiato.
- Host: GitHub
- URL: https://github.com/fnayou/dotfiles
- Owner: fnayou
- License: mit
- Created: 2026-06-15T00:00:03.000Z (25 days ago)
- Default Branch: main
- Last Pushed: 2026-06-29T18:13:32.000Z (11 days ago)
- Last Synced: 2026-06-29T20:11:26.811Z (10 days ago)
- Topics: alacritty, arch-linux, bat, catppuccin, claude-code, dotfiles, endeavouros, eza, git, gnu-stow, herdr, macos, neovim, oh-my-posh, shell, task, taskfile, zsh
- Language: Lua
- Homepage: https://fnayou.github.io/dotfiles/
- Size: 6 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# dotfiles
Private, safe, cross-platform personal dotfiles for **macOS**, **EndeavourOS / Arch Linux**, and
**Debian** (trixie / 13+), managed with [GNU Stow](https://www.gnu.org/software/stow/).
macOS is the primary environment; Arch is supported from the start, and Debian runs on all servers.
Configs are version-controlled
in `stow/common/` and only ever symlinked into `$HOME` by a **deliberate, manual** Stow step —
never automatically.
## Status
```
Claude Code operating layer: complete
GNU Stow scaffold: created
Managed packages: see stow/common/
Home directory: stowed — all stow/common/ packages symlinked into $HOME
```
`stow/common/` is the source of truth for which packages exist. All of its packages are stowed:
live symlinks point from `$HOME` into the repo. Stow is still always a deliberate, manual step.
## What's included
Each package is self-contained and carries its own README. `stow/macos/`, `stow/arch/`, and
`stow/debian/` are reserved for platform-specific packages and are currently empty.
| Package | What it manages | Details | Guide |
|---|---|---|---|
| **alacritty** | Alacritty terminal — window, font, keybinds, Catppuccin Macchiato theme | [README](stow/common/alacritty/README.md) | [guide](docs/guides/alacritty-setup.md) |
| **bat** | bat pager — style, wrap, paging, Catppuccin Macchiato theme | [README](stow/common/bat/README.md) | [guide](docs/guides/bat-setup.md) |
| **btop** | btop resource monitor — theme, background, truecolor, vim keys, Catppuccin Macchiato theme | [README](stow/common/btop/README.md) | [guide](docs/guides/btop-setup.md) |
| **claude** | Claude Code status line — OS · model · path · git · context % segments, mirrors the Catppuccin Macchiato prompt | [README](stow/common/claude/README.md) | [guide](docs/guides/claude-setup.md) |
| **eza** | eza `ls` replacement — Catppuccin Macchiato (Blue) color theme | [README](stow/common/eza/README.md) | [guide](docs/guides/eza-setup.md) |
| **git** | Portable Git config — settings, aliases, global ignore (no secrets) | [README](stow/common/git/README.md) | [guide](docs/guides/git-setup.md) |
| **herdr** | Herdr agent multiplexer — theme, terminal, UI, toast | [README](stow/common/herdr/README.md) | [guide](docs/guides/herdr-setup.md) |
| **nvim** | Neovim config — Catppuccin Macchiato (Lua), managed plugins | [README](stow/common/nvim/README.md) | — |
| **omp** | Oh My Posh prompt — segments + Catppuccin Macchiato palette | [README](stow/common/omp/README.md) | — |
| **zsh** | Layered Zsh config — path, history, plugins, tools, prompt, per-OS layers, go-task completion | [README](stow/common/zsh/README.md) | [guide](docs/guides/zsh-setup.md) |
## Documentation
The public documentation site — overview, installation, features, usage, and reference — lives at
(built with MkDocs Material from `website/`).
Setup guides are written for a human operator, not for agents.
- [Packages setup](docs/guides/packages-setup.md) — install the tools every package depends on (`git`, `stow`, `go-task`, …).
- [GNU Stow usage](docs/stow-usage.md) — dry-run workflow, install steps, conflict handling, adding packages.
- Per-package setup guides — [alacritty](docs/guides/alacritty-setup.md) · [bat](docs/guides/bat-setup.md) · [btop](docs/guides/btop-setup.md) · [claude](docs/guides/claude-setup.md) · [eza](docs/guides/eza-setup.md) · [git](docs/guides/git-setup.md) · [herdr](docs/guides/herdr-setup.md) · [zsh](docs/guides/zsh-setup.md).
- [Shell dependencies](docs/shell-dependencies.md) · [Zsh migration notes](docs/zsh-migration.md).
## Installing a package
Stow is always a manual, reviewed step. Dry-run first, install only after reviewing the output.
```bash
# Step 1 — dry run, review what would be linked
stow --dir=stow/common --target="$HOME" --simulate
```
⚠️ MANUAL STEP — run only after approving the dry-run output
```bash
stow --dir=stow/common --target="$HOME"
```
If the dry run reports a conflict, **stop** and resolve it manually. Never use `--adopt` — it
overwrites existing files. See the [Stow usage guide](docs/stow-usage.md) for full detail.
## Safety
- All `stow/common/` packages are stowed; symlinks point from `$HOME` into the repo. Each was installed via a deliberate, reviewed Stow step.
- Stow and symlink operations happen only with explicit per-session approval and a reviewed plan.
- No secrets, credentials, or private hostnames are committed.
- Local-only and sensitive values live in unstowed `.example` templates that you copy and fill in.
- Every significant change follows: PRD → Architecture → Review → Plan → Review → Build → Review → Commit.
## For Claude Code
Read `AGENTS.md` first — it is the main operating contract. It defines agent roles, the PRD-first
workflow, safety / privacy / cross-platform rules, the documentation workflow, and commit rules.
Do not implement dotfiles, run Stow, create symlinks, or modify `$HOME` without explicit user
approval and an approved plan.
## Repository structure
```
.claude/ Claude Code agents, rules, and skills
stow/
common/ Packages that work on all platforms (source of truth)
macos/ macOS-specific packages (empty)
arch/ Arch / EndeavourOS-specific packages (empty)
debian/ Debian-specific packages (empty)
docs/
guides/ Human setup guides, one per package
architecture/ Structure decisions and tradeoffs
decisions/ ADR-style decision records
plans/ Ordered implementation plans
prd/ Product requirements documents
reviews/ Review reports
claude/ Agent guides and workflow documentation
AGENTS.md Main operating contract — read this first
CLAUDE.md Claude Code entry point
```
## CI
GitHub Actions runs on every push and pull request, performing non-destructive hygiene checks only:
verifies expected files/directories exist, checks Markdown is present, runs `bash -n` on shell
scripts, and scans for obvious secret patterns. It never runs Stow, creates symlinks, modifies
`$HOME`, uses secrets, or deploys anything.
## License
See `LICENSE`.