dotfiles/CLAUDE.md

Chezmoi Dotfiles Repository - AI Assistant Guidelines

⚠️ CRITICAL: Clarify Before Acting

When in doubt, ALWAYS present options instead of guessing.

Common ambiguities that require clarification:

1. Direction: "Pull/sync changes" → Source→Target OR Target→Source?
2. Location: "Edit CLAUDE.md" → Project file OR user template?
3. Scope: Which config file when tool has multiple locations?
4. Data loss: Show diff and consequences before overwriting

See Disambiguation Guidelines for detailed examples.

Repository Context

This is a chezmoi source directory for managing dotfiles across multiple machines. Files here are SOURCE files that get templated and deployed to the home directory.

⚠️ THIS FILE vs USER-LEVEL CLAUDE.md

CRITICAL: There are THREE different CLAUDE.md/AGENTS.md files with different purposes:

1. THIS FILE (./CLAUDE.md) - Project-level, chezmoi-specific instructions

   • You are reading this file RIGHT NOW
   • Contains instructions for working with THIS chezmoi repository
   • DO NOT edit this file unless the user wants to change chezmoi-specific instructions

2. User-level (home/dot_claude/CLAUDE.md.tmpl) - User's personal AI assistant preferences

   • Deploys to ~/.claude/CLAUDE.md after chezmoi apply
   • Contains the user's personal development workflow preferences
   • Edit this file when user says "my CLAUDE.md" or "user-level CLAUDE.md"
   • Contains coding style, git workflow, build preferences, etc.

3. Global-level (~/.config/opencode/AGENTS.md) - NOT managed by this repo

   • External file, not part of chezmoi
   • Same content as user-level but lives outside this repository

When user says "my CLAUDE.md" or "user-level" → they mean home/dot_claude/CLAUDE.md.tmpl

AI Assistant Configuration

This repository manages configuration for both Claude Code (Anthropic's official CLI) and OpenCode (an enhanced fork). The configuration is symlinked and shared between both tools:

• Global guidelines live in ~/.config/opencode/AGENTS.md - this file contains cross-platform development guidelines (shell usage, build management, code style, git practices)
• Project-specific context lives in this repository's CLAUDE.md - chezmoi-specific instructions and restrictions
• Symlinking structure: The home/dot_claude/ directory creates symlinks that allow both tools to share the same configuration files (settings.json points to claude-settings.json at the repository root)
• Custom commands: Both tools share command definitions stored in home/dot_claude/commands/ (e.g., commit-staged.md, amend-commit.md, reword-commit.md)
  • IMPORTANT: When adding new command definitions to home/dot_claude/commands/, you MUST create corresponding symlinks in home/dot_config/opencode/command/
  • Symlink pattern: symlink_<command-name>.md → ../../../dot_claude/commands/<command-name>.md
  • Example: symlink_amend-commit.md contains ../../../dot_claude/commands/amend-commit.md
  • This ensures both Claude Code and OpenCode can access the same command definitions

When working in this repository, you're reading both the global AGENTS.md (general development practices) and this CLAUDE.md (chezmoi-specific guidelines). Project-specific CLAUDE.md files in other repositories take precedence over global guidelines.

Key Concepts

Source vs Target Pattern:

• Source: ~/.local/share/chezmoi/home/dot_bashrc.tmpl (what you edit)
• Target: ~/.bashrc (what gets deployed after chezmoi apply)
• Edit source files only. DO NOT modify target files directly.

File Naming Conventions:

• dot_ . (e.g., dot_bashrc becomes ~/.bashrc)
• .tmpl suffix Go template file (rendered with platform detection)
• private_ prefix 600 permissions
• encrypted_*.age age-encrypted files (safe to commit)
• run_onchange_* executable scripts that run during apply

Finding Files - Template Extension Patterns:

⚠️ CRITICAL: Most managed files have .tmpl extensions. Use wildcard patterns to find both base and .tmpl variants in one search.

Common patterns where .tmpl is added to the FULL filename:

• config.md → config.md.tmpl (NOT config.tmpl)
• settings.json → settings.json.tmpl (NOT settings.tmpl)
• config.ts → config.ts.tmpl (NOT config.tmpl)
• .bashrc → dot_bashrc.tmpl (combines dot_ and .tmpl)
• .config/opencode/opencode.jsonc → dot_config/opencode/opencode.jsonc.tmpl

Search strategy - Use wildcards to catch both variants:

• Pattern: **/filename* (e.g., **/CLAUDE.md* finds both CLAUDE.md AND CLAUDE.md.tmpl)
• Pattern: **/*.ext.tmpl for type-specific template files (e.g., **/*.ts.tmpl, **/*.json.tmpl)
• Check both home/ and home/.chezmoitemplates/ directories

Examples:

• Looking for "CLAUDE.md"? → Search **/CLAUDE.md* (finds both base and .tmpl)
• Looking for "config.nu"? → Search **/config.nu* (finds both variants)
• Looking for all TypeScript templates? → Search **/*.ts.tmpl
• Looking for all JSON configs? → Search **/*.json* (finds .json and .json.tmpl)

Template System:

• Uses Go templates with platform detection
• Two types of templates with different variable access patterns:
  • Regular templates (e.g., home/dot_bashrc.tmpl): Direct access to Chezmoi context
    • Built-in: .chezmoi.os, .chezmoi.homeDir
    • Custom data: .wsl, .chassis
  • Partials (reusable templates in home/.chezmoitemplates/): Must receive context via explicit parameter
    • Partials don't have automatic access to Chezmoi's context
    • Context passed as parameter (commonly data) when calling the partial
    • Access everything through parameter: .data.chezmoi.os, .data.wsl, .data.chassis
• Conditional rendering for Windows/Linux/macOS/WSL

Secret Management:

• Age encryption for sensitive files (recipient: age1s3ctpj9lafl6qwyvd89sn448us7gdzd53d8yyhsc7zny78c0k4sqerrkze)
• Doppler integration for API keys/tokens
• Encryption key bootstrapped via hooks from Doppler

Hooks:

• .init_pre.ts and .update_pre.ts (TypeScript via Bun)
• Bootstrap encryption key from Doppler before apply
• Handle chezmoi init and chezmoi update --init

GPG Configuration (WSL-only):

• ~/.gnupg → Symlink to Windows GPG directory (C:\Users\Xevion\AppData\Roaming\gnupg)
• /usr/local/bin/gpg → Symlink to Windows gpg.exe (via run_onchange_before_setup-wsl-gpg.sh.tmpl)
• Enables native Windows Qt5 pinentry GUI for passphrase prompts
• Automatic setup on WSL; ignored on regular Linux

Critical Restrictions

NEVER Do These Actions

1. DO NOT apply changes to filesystem

   • NO chezmoi apply
   • NO direct file writes to ~/.bashrc, ~/.gitconfig, etc.
   • Changes stay in source directory only

2. DO NOT commit or push automatically

   • NO git commit without explicit user request
   • NO git push on your own
   • Let user review changes first

3. DO NOT embed secrets in plaintext

   • NO API keys, tokens, or passwords in plain text
   • Use Doppler variables: {{ dopplerProjectJson.KEY_NAME }}
   • Use age encryption for sensitive files
   • Reference encryption: encrypted_private_*.age

4. DO NOT verify changes yourself

   • NO running build/test commands unless requested
   • Let user test changes with chezmoi diff or chezmoi apply --dry-run
   • Ask user to verify after making changes

Recommended Actions

1. Edit source files in home/ directory

   • Modify .tmpl files with proper template syntax
   • Respect platform conditionals ({{ if eq .chezmoi.os "windows" }})
   • Maintain existing template structure

2. Explain impact of changes

   • Which target files will be affected
   • Platform-specific behavior
   • What the user should test

3. Suggest verification commands

   • chezmoi diff - preview changes
   • chezmoi apply --dry-run - simulate apply
   • chezmoi status - see what's changed

4. Use templates correctly

   • Platform detection in regular templates: .chezmoi.os, .wsl, .chassis
   • Platform detection in partials: .data.chezmoi.os, .data.wsl, .data.chassis
   • Doppler secrets: {{ dopplerProjectJson.SECRET_NAME }}
   • Conditional logic: {{ if }}...{{ else }}...{{ end }}
   • Example partial call: {{ template "commonrc.sh.tmpl" . }} (passes entire context as data)

5. Suggest TODO list updates (but DO NOT modify automatically)

   • When a task is completed, check if TODO.md exists in the repository
   • If the completed task relates to items in TODO.md, suggest updating the file
   • Examples of suggestions:
     • "I've completed [task]. Would you like me to update TODO.md to mark this item as complete?"
     • "This work relates to items in TODO.md. Should I update the relevant checkboxes?"
   • NEVER modify TODO.md without explicit user approval
   • User must explicitly approve (even if not specifically) before making changes
   • Acceptable approvals: "yes", "go ahead", "update it", "sure", etc.
   • If unclear, ask: "Should I update TODO.md to reflect this completion?"

Ambiguous Phrases - Quick Reference

When you say these phrases, I should ask for clarification:

Phrase	Ambiguity	Options to Present
"Pull/sync latest changes for [file]"	Direction unclear	A) Apply source→target B) Import target→source
"Edit CLAUDE.md"	Location unclear	A) ./CLAUDE.md (project) B) home/dot_claude/CLAUDE.md.tmpl (user)
"Update [managed file]"	Source of truth unclear	A) Apply from chezmoi B) Import into chezmoi
"Add [config] to opencode"	Location unclear	A) Project opencode.jsonc B) User ~/.config/opencode/
"Show me the diff"	Comparison unclear	A) Source vs last commit B) Source vs target C) Target vs applied
"Fix the [tool] config"	Which config unclear	List all [tool] configs in repo

General rule: If a command could:

• Lose data
• Affect multiple files
• Go in opposite directions
• Reference multiple locations

→ Present options before acting

Common Tasks

Add new dotfile:

# DO NOT run - explain this to user instead
chezmoi add ~/.newconfig
# Edit: home/dot_newconfig or home/dot_newconfig.tmpl

Add sensitive config:

# DO NOT run - explain this to user instead
chezmoi add --encrypt ~/.ssh/config
# Creates: home/private_dot_ssh/encrypted_config.age

Edit existing file:

• Locate source: home/dot_config/nushell/config.nu.tmpl
• Make changes to source file
• User runs: chezmoi apply or chezmoi apply ~/.config/nushell/config.nu

Platform Coverage

• OS: Windows, Linux (WSL/native), macOS
• Shells: bash, fish, nushell, PowerShell
• Tools: 30+ development tools configured (pyenv, bun, cargo, etc.)
• Secrets: Doppler + age encryption

Disambiguation Guidelines

These situations require clarification before acting:

Chezmoi Direction Ambiguity

When user says "pull/sync/update changes" for a file, clarify the direction:

Option A: Source → Target (Normal Apply)

• Take source state and deploy to target location
• Standard chezmoi apply workflow
• Example: "Apply latest .bashrc changes to home directory"

Option B: Target → Source (Reverse/Import)

• Take target state and import to source directory
• Use chezmoi re-add or manual diff
• Example: "Import manual edits from ~/.config/foo back to chezmoi"

Red flags requiring clarification:

• "Pull latest changes for [managed file]" - which direction?
• "Update [file] with current state" - current from where?
• "Sync [file]" - which is the source of truth?

How to clarify: Present both options explicitly:

Which direction do you want?
A. Apply source → target (deploy chezmoi changes to ~/.config/foo)
B. Import target → source (pull ~/.config/foo changes into chezmoi)

File Location Ambiguity

When user references config files without full paths, clarify the location:

CLAUDE.md specifically (see details at top of this file):

• Project-level: ./CLAUDE.md (THIS file, chezmoi-specific instructions)
• User-level: home/dot_claude/CLAUDE.md.tmpl (user's personal AI preferences - deploys to ~/.claude/CLAUDE.md)
• Global-level: ~/.config/opencode/AGENTS.md (NOT managed by this repo)
• When user says "my CLAUDE.md" or "user-level" → they mean home/dot_claude/CLAUDE.md.tmpl

Other ambiguous references:

• "opencode.jsonc" - could be home/dot_config/opencode/opencode.jsonc.tmpl OR .config/opencode/opencode.jsonc
• "settings.json" - many locations (VSCode, Cursor, Claude, OpenCode)
• "config files" - which config? For what tool?

How to clarify: When user says "edit CLAUDE.md" or similar, ask:

Which file do you mean?
A. ./CLAUDE.md (project-level, chezmoi-specific instructions)
B. home/dot_claude/CLAUDE.md.tmpl (user-level, deploys to ~/.claude/CLAUDE.md)

Operations That Could Lose Data

ALWAYS confirm before these operations:

• Overwriting target files from source (could lose manual edits)
• Overwriting source files from target (could lose templated logic)
• Removing/encrypting existing files
• Changing file permissions (private_, encrypted_)
• Modifying .chezmoiignore (could expose/hide unexpected files)

How to handle:

1. Show diff/preview of what would change
2. Explicitly state what data could be lost
3. Present options with clear consequences
4. Wait for explicit confirmation

Examples of Good Clarification

Bad (assuming):

User: "Pull the latest changes for opencode.jsonc"
AI: *Shows diff of file in repo*

Good (clarifying):

User: "Pull the latest changes for opencode.jsonc"
AI: "Which operation do you want?

A. Show changes in source file (home/dot_config/opencode/opencode.jsonc.tmpl)
B. Import current target state (~/.config/opencode/opencode.jsonc) into source
   (This would OVERWRITE source with target, losing template logic)

These are very different operations - which did you mean?"

When Uncertain

1. Ask before modifying templates with complex platform logic
2. Clarify secret handling before adding sensitive data
3. Let user verify all changes before suggesting next steps
4. Prefer explanations over automated actions
5. Present options when requests are ambiguous (direction, location, scope)
6. Show consequences before destructive operations
7. USE THE QUESTION TOOL - When planning or facing design decisions, use mcp_question to present options and get user input proactively

Question Tool Usage in Chezmoi Context

STRONGLY prefer using the Question tool when working in this repository, especially for:

Planning & Ambiguity Resolution:

• Direction questions - Source→Target vs Target→Source operations
  • "Should I apply changes from source to target, or import from target to source?"
• File location questions - Which CLAUDE.md/AGENTS.md file to edit
  • "Which file should I edit: project-level CLAUDE.md or user-level home/dot_claude/CLAUDE.md.tmpl?"
• Platform targeting - Which OS/environment to optimize for
  • "Should this template prioritize Windows, Linux, or work equally on both?"
• Template complexity - How sophisticated the conditional logic should be
  • "Should I add platform detection here, or keep it simple?"

Before Making Changes:

• Encryption decisions - Whether files should be encrypted
  • "This file contains [type of data]. Should I encrypt it with age or leave it plain?"
• Permission choices - Using private_ prefix or standard permissions
  • "Should this config file use private_ prefix (600 permissions)?"
• Template vs static - Whether to use .tmpl suffix
  • "Should this be a template file, or a static file?"

Examples of good question tool usage:

User: "Add my GitHub token to the config"
AI: *Uses Question tool* "How should I handle this token?
  A. Store encrypted with age (encrypted_*.age)
  B. Reference from Doppler ({{ dopplerProjectJson.GITHUB_TOKEN }})
  C. Add to .chezmoiignore and manage manually"

User: "Update the shell config"
AI: *Uses Question tool* "Which file should I edit?
  A. home/dot_bashrc.tmpl (bash configuration)
  B. home/dot_config/nushell/config.nu.tmpl (nushell configuration)
  C. home/dot_config/fish/config.fish (fish configuration)"

When NOT to use: Trivial clarifications that don't affect functionality or security.

Remember: In a templating/dotfiles context, wrong assumptions lead to broken deployments. Always confirm when uncertain.

Extended Documentation

@README.md @TODO.md @FAQ.md @ONBOARDING.md