Dotfiles

Personal configuration files for shell environments and AI-assisted development tools.

Overview

This repository contains:

• Shell configurations: Bash, Zsh, and common shell utilities
• Git configuration: Global git settings and helpers
• Claude Code integration: Comprehensive development guidelines and MCP server configurations
• OpenCode integration: Portable custom agents
• Development tools: Prettier, Stylelint, and other code quality tools

Quick Start

For Shell Configurations

# Clone the repository
git clone https://github.com/cheshirecode/dotfiles.git ~/.dotfiles
# Source shell configurationssource~/.dotfiles/.bashrc # For Bashsource~/.dotfiles/.zshrc # For Zsh

For Claude Code

See SETUP-CLAUDE.md for complete setup instructions.

OpenCode

bin/install.sh links the custom agents in .config/opencode/agents/ into ~/.config/opencode/agents/. OpenCode configuration, API keys, and credentials remain local and are not managed by this repository.

Quick links:

• 📖 CLAUDE.md - Comprehensive development guidelines
• ⚙️ claude-mcp.example.json - MCP server configuration
• 🚀 SETUP-CLAUDE.md - Installation and setup guide

Claude Code Integration

This repository includes comprehensive documentation and configurations for using Claude Code effectively in your development workflow.

What's Included

Core Documentation

• CLAUDE.md - Complete development guidelines covering:
  • Development philosophy and best practices
  • Code quality standards
  • Git workflow and commit conventions
  • Testing strategies
  • Deployment patterns
  • Quality checklists
  • WSL-specific considerations

MCP Server Configuration

• claude-mcp.example.json - Example MCP server configuration
  • Core servers (sequential-thinking, filesystem)
  • Optional servers (github, web-search)
  • Experimental servers
  • WSL and Docker integration notes

Supporting Documentation (docs/)

• docs/mcp-servers.md - Detailed MCP server documentation

  • Setup instructions for each server
  • Authentication and API key management
  • Troubleshooting guide
  • WSL-specific Docker setup

• docs/workflows.md - Reusable development workflow patterns

  • Atomic commit workflow
  • Feature development workflow
  • Test-driven development
  • Debugging investigation
  • Safe refactoring patterns
  • WSL environment considerations

• docs/tool-mapping.md - Cursor to Claude Code migration guide

  • Comprehensive tool mapping
  • Side-by-side examples
  • Best practices and anti-patterns
  • WSL path handling

Platform Support

These configurations work on:

• ✅ Linux (native)
• ✅ macOS
• ✅ WSL (Windows Subsystem for Linux) - Extensively documented

WSL users: Special attention has been given to WSL-specific considerations including Docker Desktop integration, path handling, performance optimization, and troubleshooting.

For Cursor Users

If you're migrating from Cursor, see:

1. docs/tool-mapping.md - Tool equivalents and migration guide
2. SETUP-CLAUDE.md - "Migration from Cursor" section

The .cursor/ directory contains Cursor-specific configurations that are maintained separately.

Repository Structure

.
├── CLAUDE.md # Main Claude Code development guide
├── SETUP-CLAUDE.md # Claude Code setup instructions
├── claude-mcp.example.json # MCP server configuration template
├── claude-code-migration.plan.md # Implementation plan (reference)
├── docs/ # Supporting documentation
│ ├── mcp-servers.md # MCP server details
│ ├── workflows.md # Development workflows
│ └── tool-mapping.md # Cursor→Claude Code mapping
├── .cursor/ # Cursor-specific configurations
│ ├── mcp.json # Cursor MCP config
│ └── rules/ # Cursor AI rules
├── .bashrc # Bash configuration
├── .zshrc # Zsh configuration
├── .shell_common # Shared shell configuration
├── .bash_profile # Bash profile
├── .profile # POSIX shell profile
├── .gitconfig # Git configuration
├── .ssh-agent.sh # SSH agent helper
├── .prettierrc.js # Prettier configuration
├── .stylelintrc # Stylelint configuration
└── README.md # This file

Shell Configurations

Features

• Shared configuration: Common functions and aliases in .shell_common
• SSH agent management: Automatic SSH agent setup
• Git integration: Enhanced git aliases and helpers
• NVM support: Node Version Manager integration
• Docker helpers: Cleanup and management aliases
• WSL compatibility: Works seamlessly in WSL environments

Installation

# Clone to your home directory
git clone https://github.com/cheshirecode/dotfiles.git ~/.dotfiles
cd~/.dotfiles && bin/install.sh
# bin/install.sh is the SUPPORTED install path: detects your OS, installs# runtime deps, installs every manifest skill for Claude Code, Codex, and# Cursor (with the rmtree-safety sentinel), wires hooks, and runs# bin/doctor.sh. Idempotent — re-run is safe.## If you want manual symlinks instead, BACK UP FIRST. `ln -sf` will# silently overwrite an existing real ~/.bashrc / ~/.zshrc / ~/.gitconfig# and destroy your work. Pattern that won't bite:# for f in .bashrc .bash_profile .zshrc; do# [[ -e ~/$f && ! -L ~/$f ]] && mv ~/$f ~/$f.pre-dotfiles# done# ln -sf ~/.dotfiles/.bashrc ~/.bashrc# ln -sf ~/.dotfiles/.bash_profile ~/.bash_profile# ln -sf ~/.dotfiles/.zshrc ~/.zshrc# Reload your shellsource~/.bashrc # or source ~/.zshrc

Git Configuration

Includes:

• Useful aliases
• Better diff and merge tools
• Credential management
• WSL-compatible settings

# Link git configuration (BACK UP your existing ~/.gitconfig first!)
[[ -e~/.gitconfig &&!-L~/.gitconfig ]] && mv ~/.gitconfig ~/.gitconfig.pre-dotfiles
ln -sf ~/.dotfiles/.gitconfig ~/.gitconfig

Environment-Specific Notes

WSL (Windows Subsystem for Linux)

Important considerations for WSL users:

1. File System Performance

   • Keep projects in WSL filesystem (/home/...) for best performance
   • Avoid working in /mnt/c/... when possible (slower I/O)

2. Docker Integration

   • Use Docker Desktop for Windows with WSL2 integration
   • See docs/mcp-servers.md for Docker setup

3. Path Handling

   • WSL uses Linux paths: /home/user/project
   • Windows paths accessible via: /mnt/c/Users/...
   • Use wslpath for path conversion

4. Git Configuration

   • Configure line endings: git config --global core.autocrlf input
   • Use WSL-native git (not Windows git.exe)

5. Claude Code with WSL

   • Config location: ~/.config/claude/mcp.json (Linux path in WSL)
   • Docker MCP servers work with Docker Desktop integration
   • See SETUP-CLAUDE.md for detailed WSL setup

Contributing

Feel free to open issues or submit pull requests with improvements.

When contributing:

• Follow existing code style
• Test changes in your environment
• Update documentation as needed
• Use conventional commit messages

License

MIT License - See LICENSE file for details

Author

cheshirecode

---

Additional Resources

Claude Code

• CLAUDE.md - Development guidelines
• SETUP-CLAUDE.md - Setup guide
• docs/ - Detailed documentation

External Links

• Claude Code Documentation
• Model Context Protocol
• WSL Documentation
• Docker Desktop WSL Integration

---

Last Updated: 2026-01-21