Skip to content

CLAUDE.md

Latest commit

 

History

History
107 lines (81 loc) · 3.67 KB

CLAUDE.md

File metadata and controls

107 lines (81 loc) · 3.67 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Role

This is a showcase/reference implementation for Serotonin. The standalone Serotonin tool lives in a separate repo. This repo demonstrates a production terminal setup built with Serotonin + Chezmoi.

Project Overview

A production-ready dotfiles repository providing a modern, performance-optimized shell environment. Managed with Chezmoi for configuration templating and Sheldon for plugin management. Supports macOS and Linux (Ubuntu/Debian).

Key technologies: Zsh, Chezmoi, Sheldon (Rust-based plugin manager), Starship (prompt), Homebrew/apt, mise (multi-language version manager)

Common Commands

Serotonin (standalone, for anyone)

curl -sL dotfiles.download/serotonin | sh

This dotfiles setup (personal, uses chezmoi)

# Full install (interactive, prompts for user details)
source <(curl -sL dotfiles.download/install)

# Local install after cloning
bash scripts/dotfiles/executable_install-common.sh

Maintenance

dotfiles update       # Quick update via Serotonin (brew + sheldon + system)
dotfiles doctor       # Diagnose environment health
dotfiles-mise-update  # Update mise tool versions
chezmoi apply         # Apply template changes
sheldon lock --update # Update zsh plugins manually

Legacy dotfiles-update / dotfiles-help still work as wrappers.

Linting

# ShellCheck is used for linting (runs in CI)
shellcheck -x scripts/**/*.sh scripts/**/*.zsh

Excluded ShellCheck codes: SC1036, SC1056, SC1070, SC1072, SC1073, SC1083, SC2034, SC2139, SC2148, SC1090, SC1117, SC2206, SC1009, SC2016, SC2046, SC2154

Architecture

Configuration Flow

Chezmoi Templates (dot_*.tmpl)
    → User data from ~/.config/chezmoi/chezmoi.toml
    → Applied to home directory (~/.*)

Zsh Module Loading (dot_zshrc.d/)

The main ~/.zshrc sources modules in this order:

  1. functions.zsh - Utility functions
  2. options.zsh - Zsh options
  3. history.zsh - History configuration
  4. colors.zsh - Color schemes
  5. prompt.zsh - Prompt init (Warp native / Starship fallback)
  6. plugins.zsh - Sheldon plugin loading (uses zsh-defer for performance)
  7. alias.zsh - Shell aliases
  8. completions.zsh - Completion setup
  9. keybindings.zsh - Key bindings

Script Locations

  • scripts/dotfiles/ - Core install/update scripts
  • scripts/bin/ - Utility binaries
  • scripts/git/ - Git helper scripts
  • scripts/domain-check/ - Domain monitoring tools

Template Variables

Available in .tmpl files via Chezmoi (configured in .chezmoi.toml.tmpl):

  • {{ .fname }}, {{ .lname }}, {{ .name }} - User identity
  • {{ .email }}, {{ .email2 }} - Email addresses
  • {{ .gpgsign }}, {{ .signkey_id }} - GPG configuration
  • {{ .github_login }}, {{ .github_token }} - GitHub integration

Conventions

Scripts

  • Use executable_ prefix for scripts that should be in PATH
  • Include header with project info, author, version
  • Use set -euo pipefail for safety
  • Helper functions available: exists, fun-exists, log, confirm

Commits

Follow conventional commit format: feat|fix|chore|refactor|docs(scope): message

Plugins

Plugins are managed via Sheldon (dot_config/sheldon/plugins.toml.tmpl). Uses zsh-defer template for lazy loading. Update plugins with sheldon lock --update.

Local Overrides

Machine-specific secrets and environment variables go in ~/.config/local-shell/env.zsh (not tracked by chezmoi).

CI/CD

GitHub Actions runs on both macOS and Ubuntu:

  • ShellCheck linting on all shell scripts
  • CodeQL security scanning