English | 中文 | 日本語

---

What This Repo Is

A reproducible personal workstation setup built around:

• chezmoi for dotfiles, templating, and bootstrap orchestration
• Nix for declarative packages (nix-darwin on macOS + flakey-profile on macOS/Linux)
• aqua + mise for CLI/runtime pinning outside Nix where practical
• Shared AI tooling for Claude Code and Codex CLI

This is a real daily-driver setup, not a demo template. The README focuses on what is actually implemented in this repository today.

---

Highlights

• Unified bootstrap pipeline (.chezmoiscripts/00..11) with idempotent post-apply maintenance
• Cross-platform package strategy:
  • Nix user packages on macOS/Linux
  • nix-darwin system config on macOS
  • Homebrew/MAS integration on macOS
• Shared AI skills marketplace sync to ~/.agents/skills for both Claude and Codex
• Multi-provider account switching for both toolchains:
  • claude-manage / claude-with
  • codex-manage / codex-with
• Auto MCP sync for Claude on every chezmoi apply
• Automated dependency upkeep via GitHub Actions (versions, flake locks, aqua packages)
• OpenSpec-backed lifecycle for medium/large changes (openspec/changes, openspec/specs, opsx-*)

---

Why This Repo

• Profiles everywhere: .chezmoidata/ drives shared / work / private packages across Nix, Homebrew, and MAS
• End-to-end bootstrap: staged scripts from 00 to 11 keep setup deterministic and composable
• macOS polish: nix-darwin system defaults, Homebrew + MAS integration, post-apply maintenance scripts
• Workflow guardrails: pre-commit checks + Claude hooks to reduce risky edits and command misuse
• DX automation: Justfile routines, fzf navigation helpers, AI-assisted commit flows
• CI parity: template rendering and nix flake check on macOS + Linux matrix
• Dual AI stack: both Claude Code and Codex CLI are managed declaratively in one repo

---

Motivation

Setting up a new development machine is tedious: dozens of packages to install, many tools to configure, and years of shell/runtime tweaks to remember.

This repository solves that with a declarative baseline and practical bootstrap pipeline, so one repo can recreate a working environment across machines with predictable outcomes.

Core principles:

• Reproducibility: same setup logic, same versioned data, repeatable outcomes
• Declarative first: package and tool configuration lives in tracked YAML/templates
• Modular profiles: work/private/headless behavior is data-driven, not hardcoded forks
• AI-augmented workflows: managed prompts, hooks, skills, and provider switching
• Security layering: separate mechanisms for dotfile secrets, password store, and key backups

---

Table of Contents

• Quick Start
• First Run Prompts
• Architecture
• Repository Map
• Bootstrap Flow (What Actually Runs)
• Daily Operations
• Claude Code Integration
• AI Tooling (Claude + Codex)
• Tool Chains
• Shell Functions
• Package Management
• Multi-Profile Configuration
• Security & Secrets
• CI and Automation
• Change Management (OpenSpec)
• Additional Docs
• Acknowledgements
• Stats
• License

---

Architecture

This repository combines chezmoi templating with Nix-based package management and AI tooling overlays:

• chezmoi: source-of-truth orchestration for scripts/templates
• nix-darwin (macOS): system-level configuration
• flakey-profile (macOS/Linux): user package profile
• aqua + mise: CLI/runtime tooling layer outside Nix where needed
• dot_claude + dot_codex: tool-specific global guidance and configuration

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

---

Repository Map

.
├── .chezmoidata/
│   ├── nix.yaml                # Nix package sets (shared/work/private)
│   ├── homebrew.yaml           # Homebrew taps/brews/casks/MAS apps
│   ├── claude.yaml             # Claude provider + account model settings
│   ├── versions.yaml           # Pinned tool/plugin revisions
│   ├── aerospace.yaml          # Aerospace WM data
│   └── hammerspoon.yaml        # Hammerspoon data
├── .chezmoiscripts/            # Bootstrap + maintenance pipeline (00..11)
├── nix-config/
│   ├── flake.nix.tmpl
│   └── modules/
│       ├── system.nix.tmpl     # nix-darwin system config
│       ├── apps.nix.tmpl       # Homebrew + MAS wiring
│       ├── profile.nix.tmpl    # flakey-profile package profile
│       └── host-users.nix
├── dot_local/bin/              # CLI wrappers (Claude/Codex/keys/MCP)
├── dot_claude/                 # Claude global instructions/hooks/templates
├── dot_codex/                  # Codex global instructions/config/prompts
├── private_dot_config/         # Tool configs (tmux, mise, aqua, gopass, ...)
├── docs/                       # Focused guides
└── tests/                      # Bootstrap/script regression tests

---

Bootstrap Flow (What Actually Runs)

The chezmoi script chain is staged and numbered:

1. 00 install Nix (Determinate installer with arch/mirror detection)
2. 01 optionally restore encrypted keys-manage files (useEncryption=true)
3. 02 macOS: apply nix-darwin system configuration
4. 03 switch flakey-profile package profile
5. 04 bootstrap gopass store (interactive clone)
6. 05 install pinned aqua installer/version
7. 06 install tools from private_dot_config/aquaproj-aqua/aqua.yaml
8. 07 install runtimes/tools via mise
9. 08 install pinned nix-index database
10. 09 macOS: install/update Paperlib
11. 10 periodic Homebrew update/upgrade (7-day interval)
12. 11 sync Claude MCP servers (add/update only when needed)

---

Quick Start

Warning

This repository modifies shell, package managers, and system settings. Fork and review before running on a machine you care about.

Option 1: Run init.sh directly

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

Option 2: Pin to a tag/branch and review first

REF="<tag-or-branch>"
curl -fsSLo init.sh "https://raw.githubusercontent.com/signalridge/dotfiles/${REF}/init.sh"
shasum -a 256 init.sh || sha256sum init.sh
sh init.sh --ref "${REF}"

Option 3: Clone and run locally (best auditability)

git clone https://github.com/signalridge/dotfiles.git
cd dotfiles
git checkout <tag-or-commit>
./init.sh

Useful init.sh flags

./init.sh --repo signalridge/dotfiles
./init.sh --ref v1.2.3
./init.sh --depth 1
./init.sh --ssh

---

First Run Prompts

chezmoi data prompts include:

• work (work machine switch)
• headless (container/server without full desktop assumptions)
• useEncryption (enable encrypted key restore flow)
• installMasApps (macOS App Store apps)
• claudeProviderAccount / codexProviderAccount

For most first-time users of this repo: keep useEncryption = false unless you have your own keys-manage backup repo and key material.

---

Daily Operations

The generated global Justfile lives at ~/.config/just/.justfile.

Chezmoi

just apply
just diff
just update
just re-add

Nix

just up
just upp nixpkgs
just gc
just verify
just optimize

macOS (nix-darwin)

just darwin
just darwin-check
just darwin-build

Tests

bash tests/run.sh
pre-commit run --all-files

---

Claude Code Integration

Plugin System

Skills are synced via .chezmoiexternal.toml.tmpl from:

• wshobson/agents
• anthropics/skills
• obra/superpowers

They are normalized into ~/.agents/skills and shared by Claude/Codex.

Quality Protocols

The managed instruction stack includes explicit quality discipline patterns (for example: pre-implementation confidence checks and evidence-first verification after implementation), primarily delivered via shared skills and project-level guardrails.

Provider Management

claude-manage, claude-with, and claude-token provide account switching and provider/account-scoped model routing from .chezmoidata/claude.yaml + gopass-backed keys.

See: docs/claude-provider.md.

Hooks

Claude hooks in dot_claude/hooks/ provide workflow guardrails and formatting automation, including:

• block-git-rewrites.sh
• block-main-edits.sh
• format-code.sh
• format-python.sh

---

AI Tooling (Claude + Codex)

Shared Skill Distribution

chezmoi external syncs selected skills from:

• wshobson/agents
• anthropics/skills
• obra/superpowers

They are normalized into ~/.agents/skills and shared by Claude/Codex.

Account + Provider Control

# Claude
claude-manage
claude-manage list
claude-manage switch anthropic
claude-with kimi@private -- --resume

# Codex
codex-manage
codex-manage list
codex-manage switch openai
codex-with deepseek@private "explain this file"

Token Helpers

claude-token --check kimi@private
codex-token --check deepseek@private

MCP Integration

• Claude MCP entries are reconciled by .chezmoiscripts/run_after_11_sync-claude-mcp.sh.tmpl.
• Wrapper commands provided in this repo:
  • ~/.local/bin/mcp-tavily
  • ~/.local/bin/mcp-postgres

---

Tool Chains

This setup keeps the original modern CLI stack and shell ergonomics.

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	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	Terminal UI for git
yazi	Fast terminal file manager
tmux	Terminal multiplexer

---

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

Package lists live in .chezmoidata/ and support shared / work / private segmentation.

---

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 multiple layers with different purposes:

1. chezmoi secret decryption via age command wrapper and ~/.ssh/main
2. gopass configured with age backend for API key/password storage
3. keys-manage encrypted backup repo using OpenSSL PBKDF2 (AES-256-CBC)
4. Claude hook guardrails to block risky git/history-rewrite flows

See:

• docs/keys-manage-guide.md
• docs/gopass-new-device-setup.md
• docs/claude-provider.md

---

CI and Automation

Validation

• .github/workflows/ci.yml

  • pre-commit checks
  • template render validation
  • nix flake check (macOS + Linux matrix)

• .github/workflows/tests.yml

  • manual bootstrap/script test suite (bash tests/run.sh)

Automated Upkeep

• .github/workflows/scheduler.yml (twice weekly trigger)
• .github/workflows/update-versions.yml
• .github/workflows/update-flake-lock.yml
• .github/workflows/update-aqua-packages.yml

---

Change Management (OpenSpec)

Important

OpenSpec is the source of truth for medium/large changes in this repository.

• Change artifacts live under openspec/changes/<change-name>/ (proposal.md, design.md, tasks.md, delta specs).
• Main capability specs live under openspec/specs/<capability>/spec.md.
• Completed changes are archived under openspec/changes/archive/.
• If opsx-* wrappers are installed, they map to the same OpenSpec lifecycle.

Typical workflow:

openspec new change <change-name>
openspec status --change <change-name>
# then continue with opsx-* wrappers or openspec instructions/apply/verify/archive

---

Additional Docs

• docs/claude-provider.md
• docs/keys-manage-guide.md
• docs/gopass-new-device-setup.md
• docs/tmux.md

---

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 - Theme palette for terminal and fzf styling

---

Stats

---

License

MIT