claude-dev-setup

Claude Code Development Environment Setup

A comprehensive development environment setup for Claude Code with MCP servers, dev containers, and long-running job capabilities.

🚀 Quick Start

1. Clone this repository:

   git clone https://github.com/your-username/claude-dev-setup.git
   cd claude-dev-setup
   

2. Set up environment variables:

   cp .env.example .env
   # Edit .env with your API tokens
   

3. Start the dev container:

   # Using VS Code Dev Containers extension
   code .
   # Or using Docker Compose directly
   docker-compose up -d
   

4. Initialize MCP servers:

   ./.devcontainer/init-mcp.sh
   

5. Start a long-running job:

   ./scripts/ten-minute-job.sh
   

📋 Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Documentation
• Troubleshooting
• Contributing

✨ Features

Development Environment

• VS Code Dev Container with pre-configured extensions
• Docker-based isolated development environment
• Zsh with Oh-My-Zsh for enhanced terminal experience
• Git Delta for better diff visualization

MCP (Model Context Protocol) Servers

• Filesystem Server: File operations and project management
• Monday.com Integration: Project management and task tracking
• Figma Integration: Design system access and component management
• Playwright Integration: Browser automation and testing

Long-Running Jobs

• Auto-continuation: Jobs that persist across sessions
• Monitoring: Real-time progress tracking
• Logging: Comprehensive job logging and analysis
• Templates: Pre-built job templates for common tasks

Security & Networking

• Firewall Configuration: Automated network security setup
• Permission Management: Controlled access to system resources
• Token Management: Secure handling of API credentials

🔧 Prerequisites

• Docker Desktop or Docker Engine with Docker Compose
• VS Code with Dev Containers extension (recommended)
• Git for version control
• Node.js 20+ (included in container)

Required API Tokens

Service	Required	Purpose	How to Get
GitHub	✅ Yes	Repository operations	GitHub Settings → Developer settings → Personal access tokens
Monday.com	⚪ Optional	Project management	Monday.com → Admin → API
Figma	⚪ Optional	Design system access	Figma → Settings → Account → Personal access tokens

📦 Installation

Method 1: VS Code Dev Container (Recommended)

1. Clone and open in VS Code:

   git clone https://github.com/your-username/claude-dev-setup.git
   cd claude-dev-setup
   code .
   

2. When prompted, click "Reopen in Container"

   • VS Code will automatically build and start the dev container
   • All dependencies will be installed automatically

3. Set up environment variables:

   cp .env.example .env
   # Edit .env with your API tokens
   

Method 2: Docker Compose

1. Clone the repository:

   git clone https://github.com/your-username/claude-dev-setup.git
   cd claude-dev-setup
   

2. Configure environment:

   cp .env.example .env
   # Edit .env with your API tokens
   

3. Start the container:

   docker-compose up -d
   

4. Access the container:

   docker-compose exec claude-dev zsh
   

Method 3: Local Installation

If you prefer to run without containers:

1. Install Node.js dependencies:

   npm install -g \
     @anthropic-ai/claude-code \
     @modelcontextprotocol/server-filesystem \
     @mondaydotcomorg/monday-api-mcp \
     @playwright/mcp \
     figma-developer-mcp
   

2. Set up environment:

   cp .env.example .env
   source .env
   

3. Run initialization scripts:

   chmod +x .devcontainer/*.sh scripts/*.sh
   ./.devcontainer/init-mcp.sh
   

⚙️ Configuration

Environment Variables

Edit .env file with your configuration:

# Required: GitHub Personal Access Token
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

# Optional: Monday.com API token
MONDAY_API_TOKEN=your_monday_token_here

# Optional: Figma API token
FIGMA_TOKEN=your_figma_token_here

# Optional: Timezone (defaults to UTC)
TZ=America/New_York

# Optional: Node.js memory limit
NODE_OPTIONS=--max-old-space-size=8192

MCP Server Configuration

MCP servers are automatically configured during container startup. To manually configure:

# Add MCP servers to Claude
claude mcp add filesystem "npx @modelcontextprotocol/server-filesystem /workspace"
claude mcp add monday "npx @mondaydotcomorg/monday-api-mcp --token $MONDAY_API_TOKEN"
claude mcp add playwright "npx @playwright/mcp"
claude mcp add figma "npx figma-developer-mcp --figma-api-key=$FIGMA_TOKEN --stdio"

# Verify configuration
claude mcp list

🎯 Usage

Quick Commands

# Start MCP servers
./.devcontainer/start-mcps.sh

# Run a 10-minute demo job
./scripts/ten-minute-job.sh

# Start custom long-running job
./scripts/run-long-claude-job.sh "Your task description"

# Monitor job progress
./scripts/monitor-job.sh /workspace/claude-job-*.log

# Check system status
docker-compose ps
ps aux | grep claude

Development Workflow

1. Start development environment:

   # Open in VS Code
   code .
   # Or start container manually
   docker-compose up -d
   

2. Initialize your project:

   # Create new project
   mkdir my-project && cd my-project
   npm init -y
   
   # Start Claude Code
   claude-code --dangerously-skip-permissions
   

3. Run long-running analysis:

   ./scripts/ten-minute-job.sh
   # Monitor in another terminal
   tail -f /workspace/claude-job-*.log
   

Job Templates

Code Analysis

./scripts/run-long-claude-job.sh "
Perform comprehensive code analysis:
1. Review all components for performance issues
2. Identify security vulnerabilities  
3. Suggest architectural improvements
4. Generate detailed report with recommendations
"

Documentation Generation

./scripts/run-long-claude-job.sh "
Create comprehensive documentation:
1. Add JSDoc comments to all functions
2. Create API documentation
3. Write usage examples for components
4. Generate architecture diagrams
"

Testing Setup

./scripts/run-long-claude-job.sh "
Set up comprehensive testing infrastructure:
1. Configure Jest and testing libraries
2. Create test files for existing components
3. Set up E2E testing with Playwright
4. Add test coverage reporting
"

📚 Documentation

• MCP Setup Guide - Detailed MCP server configuration
• Long-Running Jobs - Job management and monitoring
• Dev Container Guide - Container configuration details
• Troubleshooting Guide - Common issues and solutions

🔍 Monitoring and Debugging

Check System Status

# Container status
docker-compose ps

# MCP server status
ps aux | grep mcp

# Claude processes
ps aux | grep claude

# Resource usage
docker stats

Log Files

# MCP server logs
tail -f /tmp/mcp-server.log
tail -f /tmp/monday-mcp.log
tail -f /tmp/figma-mcp.log
tail -f /tmp/playwright-mcp.log

# Job logs
tail -f /workspace/claude-job-*.log

# Container logs
docker-compose logs -f claude-dev

Health Checks

# Test MCP connections
claude mcp test filesystem
claude mcp test monday
claude mcp test playwright
claude mcp test figma

# Network connectivity
ping github.com
curl -I https://api.monday.com

🐛 Troubleshooting

Common Issues

Container Won't Start

# Check Docker daemon
docker version

# Check disk space
df -h

# Rebuild container
docker-compose down
docker-compose build --no-cache
docker-compose up -d

MCP Servers Not Working

# Restart MCP servers
pkill -f mcp
./.devcontainer/init-mcp.sh

# Check environment variables
echo $MONDAY_API_TOKEN
echo $FIGMA_TOKEN

# Verify installations
npm list -g | grep mcp

Long-Running Jobs Failing

# Check Claude authentication
claude-code --version

# Verify permissions
ls -la /workspace

# Check available memory
free -m

# Review error logs
grep -i error /workspace/claude-job-*.log

Getting Help

1. Check logs for specific error messages
2. Review documentation in the docs/ directory
3. Search issues in the GitHub repository
4. Create an issue with:
   • Error messages
   • Steps to reproduce
   • Environment details (docker version, node --version)

🔒 Security Considerations

• API Tokens: Store in .env file, never commit to repository
• Permissions: Use --dangerously-skip-permissions only in trusted environments
• Network: Firewall rules are automatically configured
• Container: Runs with non-root user by default

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and test thoroughly
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

Development Guidelines

• Follow existing code style and conventions
• Add documentation for new features
• Test changes in both container and local environments
• Update relevant documentation files

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Anthropic for Claude Code and MCP protocol
• Microsoft for VS Code Dev Containers
• Docker for containerization platform
• Community contributors for improvements and feedback

📞 Support

• Documentation: Check the docs/ directory
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Happy Coding with Claude! 🎉