convez.ai
AgenteDevOps & InfraestruturaAvançado
signalridge

Dotfiles Declarativos com Chezmoi + Nix

signalridge/dotfiles

Workstation declarativa multiplataforma com chezmoi, Nix e integração IA

Ver no GitHub
BomPluginScore · de 0 a 100

Ambiente de desenvolvimento reproduzível para macOS e Linux usando chezmoi para orquestração de dotfiles, Nix para gerenciamento declarativo de pacotes, e integração automática com ferramentas de IA (Claude Code, Codex CLI). Implementa sincronização de MCP, perfis multi-contexto e pipeline idempotente de bootstrap.

Instalação

$npx convez-ai signalridge/dotfiles

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
46
Forks
3
Acompanhando
1
Saúde
57%
Último commit
há 1 dia
Versão
—
Issues abertas
0
Contribuidores
4

Casos de uso

  • Sincronizar ambiente de desenvolvimento entre máquinas macOS/Linux
  • Automatizar setup inicial e manutenção de dependências via GitHub Actions
  • Gerenciar múltiplos perfis de trabalho (pessoal, corporativo, privado) com templating

Veredito

Solução madura e battle-tested para quem precisa de IaC no nível de workstation pessoal. Curva de aprendizado alta (chezmoi + Nix), mas entrega reprodutibilidade real e integração nativa com ecossistema IA modern.

README

A tradução para o português deste README ainda está na fila.

header

English | 中文 | 日本語

Typing SVG


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..12) 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 ~/.harnesses/skills outside Codex auto-discovery
  • Multi-provider account switching for managed wrappers:
    • 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)

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: 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


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
ComponentmacOSLinux
Dotfileschezmoichezmoi
System Confignix-darwinN/A
User Packagesflakey-profileflakey-profile
GUI AppsHomebrew/MASN/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..12)
├── 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 install pinned aqua installer/version
  6. 05 install tools from private_dot_config/aquaproj-aqua/aqua.yaml (including mise)
  7. 06 bootstrap gopass store (interactive clone)
  8. 07 install runtimes/tools via aqua-managed 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: Download init.sh then run interactively

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

Why not curl … | sh? chezmoi init prompts for hostname, GitHub username, email, etc. Piping into sh detaches stdin from your terminal, so those prompts have nothing to read from and the install bails out (or worse, would silently write placeholder values). Download first, then run — sh /tmp/init.sh keeps your TTY attached.

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
DOTFILES_USE_ENCRYPTION=false ./init.sh

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.

First-run is interactive. Identity prompts (hostname, gitUsername, useremail, gitEmail) have no safe default and will hard-fail if there's no TTY — use Option 1's download-then-run pattern, not pipe-to-sh. On a re-apply where ~/.config/chezmoi/chezmoi.toml already has these values, prompts are skipped; DOTFILES_USE_ENCRYPTION=true|false lets you override the encryption flag from the environment in that case.


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:

  • broad engineering packs such as wshobson/agents, anthropics/skills, and openai/skills
  • platform/vendor packs from Hugging Face, Cloudflare, Vercel, Supabase, Expo, Microsoft, and selected community repos
  • language suites for Go, Rust, Swift, TypeScript/JavaScript, and Zig
  • social, writing, and media skills including xurl, x-create, daily.dev, Reddit, Remotion, and Humanizer variants (humanizer-en, qu-ai-wei, humanizer-ja)

They are normalized into ~/.harnesses/skills as a shared library; use skill-activate from a project directory to curate active symlinks in ./.claude/skills and ./.codex/skills. skill-activate --category typescript activates a whole category for the current directory, skill-activate --sync repairs existing Claude-only/Codex-only partial pairs, and Ctrl-A toggles the highlighted category in the picker.

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:

  • broad engineering packs (wshobson/agents, anthropics/skills, openai/skills)
  • platform/vendor packs (Hugging Face, Cloudflare, Vercel, Supabase, Expo, Microsoft, and selected community repos)
  • language suites for Go, Rust, Swift, TypeScript/JavaScript, and Zig
  • social, writing, and media skills including xurl, x-create, daily.dev, Reddit, Remotion, and Humanizer variants (humanizer-en, qu-ai-wei, humanizer-ja)

They are normalized into ~/.harnesses/skills as a shared library; use skill-activate from a project directory to curate active symlinks in ./.claude/skills and ./.codex/skills. skill-activate --category typescript activates a whole category for the current directory, skill-activate --sync repairs existing Claude-only/Codex-only partial pairs, and Ctrl-A toggles the highlighted category in the picker.

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-context7
    • ~/.local/bin/mcp-tavily
    • ~/.local/bin/mcp-postgres

Task -> MCP Routing

Task typePrimary MCPFallback
Library/framework/API docsContext7Tavily -> built-in web search
Web/news/general researchTavilybuilt-in web search
Symbolic code navigationSerenarepo grep/codesearch + LSP

Tool Chains

Classic Unix tools get aliased modern replacements; on top sits a domain-organized set of power-user CLIs. Everything is version-pinned via aqua.

Drop-in Replacements

ClassicModernWhy
lsezaGit-aware listing, icons, tree views
catbatSyntax highlighting, git integration
grepripgrepLightning-fast regex search
findfdIntuitive syntax, respects .gitignore
cdzoxideFrecency-based directory jumping
dudustReadable disk-usage tree
mantlrcFast Rust tldr client

Shell & Prompt

ToolRole
starshipMinimal, blazing-fast prompt
sheldonFast zsh plugin manager
atuinShell history with fuzzy search
direnvPer-directory environment variables
fzfFuzzy finder for files, history, and more
carapaceCross-shell completions for many CLIs
vividLS_COLORS theme generator

Editor, Files & Git

ToolRole
misePolyglot runtime manager (Node/Python/Go/Rust)
yaziFast terminal file manager
tmuxTerminal multiplexer
lazygit / lazydockerTerminal UIs for git / Docker
jjJujutsu VCS (git-compatible)
git-cliffChangelog generator
delta / difftasticSyntax-aware diffs

Domain-Specific CLIs

DomainTools
Code & searchast-grep, watchexec, typos, ruff, ty, prek
HTTP & APIxh, Posting, Slumber, oha
Containers & K8sk9s, kubectl, Helm, stern, kubecolor, kubectx, krew
Security & SBOMzizmor, Gitleaks, Trivy, Syft, Grype
System & networkbottom, procs, lnav, hexyl, doggo, hyperfine
Archive & mediaouch, gum, vhs
AI usageccusage, @ccusage/codex

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

SourcePlatformDescription
Nix packagesmacOS, LinuxReproducible, rollback-able
Homebrew casksmacOS onlyGUI applications
Mac App StoremacOS onlyApp 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

Additional Docs

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

Acknowledgements


Stats

Alt


License

MIT

Ver o original no GitHub

Bom para

Relacionados