English | 中文 | 日本語

---

✨ Highlights

• Cross-platform: One repo for macOS + Linux (nix-darwin + flakey-profile)
• One-command bootstrap: From bare metal to full environment with a single curl | sh
• Claude Code integration: 50+ plugins from multiple sources with automated sync
• Modern CLI: Rust-based tools (eza, bat, ripgrep, fd, zoxide) replacing Unix classics
• Security-first: age encryption with gopass-assisted key bootstrapping

---

💡 Why This Repo

• Profiles everywhere: .chezmoidata/ drives shared / work / private packages across Nix, Homebrew, and MAS
• End-to-end bootstrap: Nix installer auto-selects fastest Determinate mirror, chezmoi renders and applies templates in one flow
• macOS polish: nix-darwin system defaults, Homebrew + MAS integration, post-apply update scripts
• Workflow guardrails: pre-commit (shellcheck, markdownlint, prettier, Nix lint) + Claude Code hooks
• DX automation: Justfile routines, fzf navigation helpers, AI-assisted commit messages
• CI parity: Template rendering and nix flake check run on macOS + Linux
• Claude Code hooks: Auto-format code, enforce uv over pip, block main branch edits

---

🎯 Motivation

Setting up a new development machine is tedious: dozens of packages to install, countless tools to configure, and years of tweaks to remember. This repository solves that with fully declarative configuration - every package, setting, and dotfile defined in code, reproducible across any machine with one command.

Core principles:

• Reproducibility — Same environment on any machine, every time
• Declarative — Everything defined in code, version controlled
• Modular — Profile-based customization for work/personal/headless
• AI-augmented — Claude Code integration for development workflows
• Security-first — Encrypted secrets with gopass integration

---

📑 Table of Contents

• 🚀 Quick Start
• 🧩 Architecture
• 🤖 Claude Code Integration
• ⚡ Tool Chains
• 🔧 Shell Functions
• 📦 Package Management
• 🔄 Daily Operations
• 👤 Multi-Profile Configuration
• 🔐 Security & Secrets
• 🙏 Acknowledgements

---

Warning

Review before running! This repository contains scripts that will modify your system configuration. Fork this repository and customize it for your own needs.

---

🚀 Quick Start

Option 1: Run init script directly from GitHub (recommended)

curl -fsLS https://raw.githubusercontent.com/signalridge/dotfiles/main/init.sh | sh

Option 2: Install chezmoi and init

sh -c "$(curl -fsLS get.chezmoi.io)" -- init --apply signalridge

Option 3: Clone and run locally

git clone https://github.com/signalridge/dotfiles.git
cd dotfiles && ./init.sh

This will automatically:

1. Install Nix (Determinate Systems installer)
2. Install age and gopass for secrets decryption
3. Fetch encryption key from gopass (or prompt for manual setup)
4. Apply all dotfiles and configurations
5. Sync Claude Code plugins from marketplace

Important

First-time users: When prompted for useEncryption, answer No (default). The encryption setup is specific to the repo owner. If you need encryption, modify:

• .chezmoiscripts/run_once_before_01_setup-encryption-key.sh: Change KEY_FILE, KEY_PUB, and gopass secret path
• .chezmoi.toml.tmpl: Update identity and recipientsFile paths in [age] section

After installation, restart your terminal. For macOS, run just darwin to activate nix-darwin configuration.

---

🧩 Architecture

~/.dotfiles/
├── .chezmoidata/           # Modular data configuration
│   ├── base.yaml           # Core settings
│   ├── claude.yaml         # Claude Code plugin configuration
│   └── versions.yaml       # Pinned tool versions
├── .chezmoiscripts/        # Bootstrap & sync scripts
├── dot_claude/             # Claude Code configuration
│   ├── agents/             # AI agent definitions
│   ├── commands/           # Slash commands
│   ├── skills/             # Auto-knowledge skills
│   ├── hooks/              # Git & code hooks
│   └── context/            # Reference documentation
├── nix-config/             # Nix flake configuration
│   └── modules/            # nix-darwin / flakey-profile modules
└── dot_custom/             # Shell functions & aliases

chezmoi manages dotfiles across machines with templating, secrets, and platform-specific conditionals.

nix-darwin (macOS) provides declarative system configuration through Nix, managing system packages, Homebrew, and macOS preferences.

flakey-profile (Linux) provides declarative package management using the same Nix flake, focused on user packages.

Component	macOS	Linux
Dotfiles	chezmoi	chezmoi
System Config	nix-darwin	N/A
User Packages	flakey-profile	flakey-profile
GUI Apps	Homebrew Cask	N/A

---

🤖 Claude Code Integration

This dotfiles includes a comprehensive Claude Code setup with automated plugin management.

Plugin System

Plugins are automatically downloaded via .chezmoiexternal.toml.tmpl from multiple sources:

Source	Description
wshobson/agents	50+ community plugins (agents, commands, skills)
anthropics/skills	Official document processing (pdf, docx, pptx, xlsx)
obra/superpowers	Advanced workflow patterns

# .chezmoidata/claude.yaml
claude:
  wshobsonAgents:
    include:
      - python-development
      - javascript-typescript
      - backend-development
      - tdd-workflows
      - cloud-infrastructure
      # ... 19 plugins enabled
  anthropicsSkills:
    include:
      - pdf
      - docx

chezmoi external automatically:

• Downloads enabled plugins on chezmoi apply
• Extracts agents, commands, and skills into ~/.claude/
• Updates when plugin configuration changes

Quality Protocols

Built-in quality assurance inspired by SuperClaude:

Protocol	Purpose
Confidence Check	Pre-implementation assessment (HIGH/MEDIUM/LOW)
Self-Check	Post-implementation verification with evidence

Hooks

Hook	Trigger	Action
format-code.sh	After Edit/Write	Auto-format Nix, JSON, YAML, Shell, Go, Lua
enforce-uv.sh	On pip commands	Redirect to uv for Python
block-main-edits.sh	On file edit	Prevent direct edits to main branch
block-git-rewrites.sh	On git commands	Block force push and history rewrites

---

⚡ Tool Chains

This setup replaces traditional Unix tools with modern, Rust-based alternatives.

Modern CLI Replacements

Classic	Modern	Description
ls	eza	Git integration, icons, tree views
cat	bat	Syntax highlighting, git integration
grep	ripgrep	Lightning-fast regex search
find	fd	Intuitive syntax, respects .gitignore
cd	zoxide	Smart directory jumping

Shell Environment

Tool	Role
starship	Minimal, blazing-fast prompt
sheldon	Fast zsh plugin manager
atuin	Magical shell history with fuzzy search
direnv	Per-directory environment variables
fzf	Fuzzy finder for files, history, and more

Development Tools

Tool	Role
mise	Polyglot runtime manager (Node, Python, Go, Rust)
lazygit	Beautiful terminal UI for git
yazi	Blazing fast terminal file manager
tmux	Terminal multiplexer with floating panes

---

🔧 Shell Functions

Project Navigation

dev                 # FZF-powered project selector (with ghq)
mkcd <dir>          # Create directory and cd into it
dotcd               # Jump to chezmoi source

Git Workflow

fgc                 # Fuzzy git checkout (branches)
fgl                 # Fuzzy git log viewer
fga                 # Fuzzy git add (select files)
aicommit            # Generate commit message with AI

Environment Setup

create_direnv_venv  # Create Python venv with direnv
create_direnv_nix   # Create Nix flake with direnv
create_py_project   # Quick Python project setup with uv

---

📦 Package Management

Source	Platform	Description
Nix packages	macOS, Linux	Reproducible, rollback-able
Homebrew casks	macOS only	GUI applications
Mac App Store	macOS only	App Store exclusives

All package lists are defined in .chezmoidata/ with support for shared, work-only, and private-only packages.

---

🔄 Daily Operations

# Chezmoi operations
just apply          # Apply dotfile changes
just diff           # Show pending changes

# Nix operations
just up             # Update all flake inputs
just switch         # Switch flakey-profile (rebuild packages)
just darwin         # Rebuild nix-darwin (macOS)

# Maintenance
just gc             # Garbage collect nix store
just full-upgrade   # Complete system upgrade

---

👤 Multi-Profile Configuration

# For work machines
chezmoi init --apply --promptBool work=true signalridge

# For personal machines (default)
chezmoi init --apply signalridge

# For headless servers (no GUI configs)
chezmoi init --apply --promptBool headless=true signalridge

---

🔐 Security & Secrets

This repo uses age encryption for private files. Chezmoi decrypts using ~/.ssh/main (private key) and ~/.ssh/main.pub (recipient).

On first apply, bootstrap scripts will:

1. Install Nix
2. Install age + gopass via nix
3. Fetch the key from gopass (or prompt for manual setup)

---

🙏 Acknowledgements

• chezmoi - Dotfiles manager
• nix-darwin - Declarative macOS configuration
• flakey-profile - Cross-platform Nix profile management
• wshobson/agents - Claude Code plugins marketplace
• anthropics/skills - Official Claude Code skills
• obra/superpowers - Advanced workflow patterns
• Dracula Theme - Beautiful dark theme

---

📈 Stats

---

📝 License

MIT License