home/CLAUDE.md

CLAUDE.md

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

Overview

This is a personal home directory repository managed as a git repository with selective tracking via .gitignore. The repository tracks dotfiles and configuration for a Debian development environment supporting Node.js, Python, Ruby, Rust, and Go development.

Key Architecture

Initialization System

Shell initialization is managed through .init/init.sh, which sources modular configuration:

• .init/path.sh - PATH environment setup for all language toolchains
• .init/alias.sh - Custom shell aliases
• .init/functions.sh - Custom shell functions for deployment and media processing
• .init/export.sh, .init/source.sh, .init/eval.sh - Additional environment setup

Arty Configuration

arty.yml defines the repository structure using Arty (artifact/repository manager):

• references: Git subrepositories to clone into specific paths
• envs: Environment profiles (dev/prod) for selective repository management
• Manages both development projects and language version managers (nvm, rbenv, pyenv, gvm)

Ansible Provisioning

playbook.yml is an Ansible playbook for system setup:

• Installs and configures language runtimes (Node, Python, Ruby, Rust, Go)
• Sets up Docker, PostgreSQL 18, and development tools
• Configures Zsh with Oh-My-Zsh and Powerlevel10k theme
• Manages system packages via apt

Git Selective Tracking

The .gitignore uses an inverted pattern (ignore everything, then selectively allow):

• Tracks only specific dotfiles and configuration files
• Allows .github/, .init/, .vscode/ directories
• Excludes logs, databases, and temporary files

Development Environment

Language Version Management

• Node.js: Managed by nvm, version specified in .nvmrc
• Ruby: Managed by rbenv, version in .ruby-version
• Python: Managed by pyenv, version in .python-version
• Rust: Via rustup (.cargo/, .rustup/)
• Go: Via gvm (.gvm/)

Shell Environment

• Shell: Zsh with Oh-My-Zsh framework
• Theme: Powerlevel10k (.p10k.zsh)
• Plugins: git, pm2, gh, docker, language-specific plugins, zsh-autosuggestions, zsh-syntax-highlighting

Common Commands

Environment Setup

# Reinitialize shell environment
ri  # alias for: source ~/.init/init.sh

# Bootstrap system (run as user, prompts for sudo)
sudo -u $USER ansible-playbook -K playbook.yml

# Run specific Ansible tags
ansible-playbook --tags node,python,ruby -K playbook.yml

Arty Repository Management

# Debug Arty configuration
pnpm arty debug

# Clone/update repositories based on environment
pnpm arty sync --env dev

Git Workflow

# Stage all changes and check if clean
g0  # alias for: git add . && git diff --quiet && git diff --cached --quiet

# Reset to single commit
g1  # alias for: git reset $(git commit-tree "HEAD^{tree}" -m "A new start")

# Get last commit message
g2  # alias for: git log --format=%B -n 1 HEAD | head -n 1

Code Quality

# Python pre-commit hooks (configured in .pre-commit-config.yaml)
pre-commit run --all-files

# Ruby style checking
rubocop

# Node.js linting
pnpm eslint

Utility Functions

Available shell functions from .init/functions.sh:

• batch_file_sequence <prefix> <extension> - Rename files with sequence numbers
• batch_image_webp - Convert images to WebP format
• batch_video_x264 - Convert videos to x264 codec
• rs - Rsync with sudo on remote (alias for complex rsync command)
• ss - Serve current directory on port 8000
• yt <url> - Download YouTube video as MP3

Projects Structure

The Projects/ directory contains development projects:

• butter-sh/ - Butter shell projects
• docker-compose/ - Docker compose configurations
• pivoine.art/ - Jekyll-based art portfolio site
• docs.pivoine.art/ - Documentation site
• sexy.pivoine.art/ - Includes Rust package (packages/buttplug/)
• node.js/ - Node.js applications (awesome, awesome-app, email-pour-vous, webshot)

Package Management

Node.js

• Package manager: pnpm (enabled via corepack)
• Global packages: Installed to ~/node_modules/
• PM2: Configured via ecosystem.config.js for GitHub Copilot language server

Python

• Installer: pip
• Dependencies: Listed in requirements.txt (currently: pre-commit)

Ruby

• Bundler: Gemfile specifies Jekyll 4.3 and rubocop

Important Notes

• This repository uses selective git tracking - most files are ignored by default
• Shell must source .init/init.sh for full environment setup (automatically done in .zshrc)
• Language runtimes are version-managed and installed via Ansible
• Docker requires user to be in docker group (managed by Ansible)
• The .last_pwd file tracks the last working directory for shell navigation