Skip to content

Latest commit

 

History

History
506 lines (394 loc) · 13.5 KB

CONTRIBUTING.md

File metadata and controls

506 lines (394 loc) · 13.5 KB

Contributing to Claude Code Templates

We welcome contributions! Help us make Claude Code even better for everyone.

📋 Before contributing, please read our Code of Conduct to ensure a respectful and inclusive environment for all community members.

🧩 Contributing Components

The easiest way to contribute is by adding individual components like agents, commands, MCPs, settings, or hooks.

🤖 Adding Agents

Agents are AI specialists for specific domains (security, performance, frameworks, etc.).

  1. Create Agent File

    # Navigate to appropriate category
cd cli-tool/components/agents/[category]/

# Create your agent file
touch your-agent-name.md

  2. Agent File Structure

    # Agent Name

Agent description and purpose.

## Expertise
- Specific domain knowledge
- Key capabilities
- Use cases

## Instructions
Detailed instructions for Claude on how to act as this agent.

## Examples
Practical examples of agent usage.

  3. Available Categories

    • development-team/ - Full-stack developers, architects
    • domain-experts/ - Security, performance, accessibility specialists
    • creative-team/ - Content creators, designers
    • business-team/ - Product managers, analysts
    • development-tools/ - Tool specialists, DevOps experts

  4. Creating New Categories If your agent doesn't fit existing categories, create a new one:

    # Create new category folder
cd cli-tool/components/agents/
mkdir your-new-category

# Add your agent file to the new category
cd your-new-category/
touch your-agent-name.md

⚡ Adding Commands

Commands are custom slash commands that extend Claude Code functionality.

  1. Create Command File

    cd cli-tool/components/commands/[category]/
touch your-command-name.md

  2. Command File Structure

    # /command-name

Brief command description.

## Purpose
What this command accomplishes.

## Usage
How to use the command with examples.

## Implementation
Technical details of what the command does.

  3. Command Categories

    • code-generation/ - Generate code, tests, documentation
    • analysis/ - Code analysis, optimization, debugging
    • project-management/ - File operations, project structure
    • testing/ - Test generation, validation, coverage
    • deployment/ - Build, deploy, CI/CD operations

  4. Creating New Categories If your command doesn't fit existing categories, create a new one:

    # Create new category folder
cd cli-tool/components/commands/
mkdir your-new-category

# Add your command file to the new category
cd your-new-category/
touch your-command-name.md

🔌 Adding MCPs (Model Context Protocol)

MCPs provide external service integrations for Claude Code.

  1. Create MCP File

    cd cli-tool/components/mcps/[category]/
touch your-service-mcp.json

  2. MCP File Structure

    {
  "mcpServers": {
    "service-name": {
      "command": "npx",
      "args": ["-y", "@your-org/mcp-server"],
      "env": {
        "API_KEY": "<YOUR_API_KEY>",
        "BASE_URL": "https://api.service.com"
      }
    }
  }
}

  3. MCP Categories

    • audio/ - Audio processing, text-to-speech, transcription services
    • integration/ - GitHub, GitLab, Jira
    • database/ - PostgreSQL, MySQL, MongoDB
    • cloud/ - AWS, Azure, GCP services
    • devtools/ - Build tools, testing frameworks
    • ai-services/ - OpenAI, Anthropic, other AI APIs

  4. Creating New Categories If your MCP doesn't fit existing categories, create a new one:

    # Create new category folder
cd cli-tool/components/mcps/
mkdir your-new-category

# Add your MCP file to the new category
cd your-new-category/
touch your-service-mcp.json

⚙️ Adding Settings

Settings configure Claude Code behavior and performance.

  1. Create Settings File

    cd cli-tool/components/settings/[category]/
touch your-setting-name.json

  2. Settings File Structure

    {
  "setting-category": {
    "parameter": "value",
    "description": "What this setting controls"
  }
}

  3. Settings Categories

    • performance/ - Memory, timeout, cache settings
    • ui/ - Interface customization, themes
    • mcp/ - MCP server configurations
    • security/ - Access control, permissions

  4. Creating New Categories If your setting doesn't fit existing categories, create a new one:

    # Create new category folder
cd cli-tool/components/settings/
mkdir your-new-category

# Add your setting file to the new category
cd your-new-category/
touch your-setting-name.json

🪝 Adding Hooks

Hooks provide automation triggers for different development events.

  1. Create Hook File

    cd cli-tool/components/hooks/[category]/
touch your-hook-name.json

  2. Hook File Structure

    {
  "hooks": {
    "hook-name": {
      "event": "trigger-event",
      "command": "action-to-perform",
      "description": "What this hook does"
    }
  }
}

  3. Hook Categories

    • git/ - Pre-commit, post-commit, pre-push
    • development/ - File changes, build events
    • testing/ - Test execution, coverage checks

  4. Creating New Categories If your hook doesn't fit existing categories, create a new one:

    # Create new category folder
cd cli-tool/components/hooks/
mkdir your-new-category

# Add your hook file to the new category
cd your-new-category/
touch your-hook-name.json

📦 Contributing Templates

Templates are complete project configurations that include CLAUDE.md, .claude/* files, and .mcp.json.

Creating New Templates

  1. Create Template Directory

    cd cli-tool/templates/
mkdir your-template-name
cd your-template-name

  2. Template Structure

    your-template-name/
├── CLAUDE.md                    # Main configuration
├── .claude/
│   ├── settings.json           # Automation hooks
│   └── commands/               # Template-specific commands
├── .mcp.json                   # MCP server configuration
└── README.md                   # Template documentation

  3. CLAUDE.md Guidelines

    • Include project-specific configuration
    • Add development commands and workflows
    • Document best practices and conventions
    • Include security guidelines
    • Provide testing standards

  4. Template Categories

    • Framework-specific (React, Vue, Angular, etc.)
    • Language-specific (Python, TypeScript, Go, etc.)
    • Domain-specific (API development, machine learning, etc.)
    • Industry-specific (e-commerce, fintech, etc.)

Template Quality Standards

  • Comprehensive Configuration - Include all necessary Claude Code setup
  • Clear Documentation - Well-documented CLAUDE.md with examples
  • Practical Commands - Useful slash commands for the domain
  • Proper MCPs - Relevant external integrations
  • Testing - Test template with real projects

🛠️ Contributing to Additional Tools

For advanced contributors who want to improve the CLI tools like analytics, health check, and chat monitoring.

🚀 Development Setup

Prerequisites

  • Node.js 14+ (for the installer)
  • npm or yarn
  • Git

Project Setup

# Clone the repository
git clone https://github.com/davila7/claude-code-templates.git
cd claude-code-templates

# Navigate to the CLI tool directory
cd cli-tool

# Install dependencies
npm install

# Link for local testing
npm link

# Run test suite
npm test

📊 Analytics Dashboard Development

The analytics dashboard provides real-time monitoring of Claude Code sessions.

Development Workflow

# Start analytics dashboard
npm run analytics:start

# Clear cache during development
curl -X POST http://localhost:3333/api/cache/clear -H "Content-Type: application/json" -d '{"type":"all"}'

# Refresh data
curl http://localhost:3333/api/refresh

# Restart server completely
pkill -f analytics && sleep 3 && npm run analytics:start

Architecture

src/analytics/
├── core/                     # Business logic
│   ├── StateCalculator.js   # Conversation state detection
│   ├── ProcessDetector.js   # Running process detection
│   ├── ConversationAnalyzer.js # Message parsing
│   └── FileWatcher.js       # Real-time file monitoring
├── data/                    # Data management
│   └── DataCache.js        # Multi-level caching
├── notifications/           # Real-time communication
│   ├── WebSocketServer.js  # Server-side WebSocket
│   └── NotificationManager.js # Event-driven notifications
└── utils/                   # Utilities
    └── PerformanceMonitor.js # System health monitoring

Common Development Issues

Problem: Changes don't appear in dashboard

# Solution: Clear cache and refresh
curl -X POST http://localhost:3333/api/cache/clear -H "Content-Type: application/json" -d '{"type":"conversations"}'
curl http://localhost:3333/api/refresh

Problem: WebSocket not updating

# Solution: Hard refresh browser (Ctrl+F5 or Cmd+Shift+R)

💬 Chat Monitor Development

Mobile-optimized interface for viewing Claude conversations in real-time.

Architecture

src/chats/
├── components/              # UI components
├── services/               # API communication
├── websocket/              # Real-time updates
└── styles/                 # Mobile-first CSS

Development Commands

# Start chat monitor
npm run chats:start

# Start with tunnel (requires cloudflared)
npm run chats:start -- --tunnel

# Test mobile interface
npm run chats:test

🔍 Health Check Development

Comprehensive diagnostics tool for Claude Code installations.

Health Check Categories

  • Installation Validation - Claude Code setup verification
  • Configuration Check - Settings and file validation
  • Performance Analysis - Memory, disk, network diagnostics
  • Security Audit - Permission and access checks

Development

# Run health check
npm run health-check

# Add new health check
# 1. Create check in src/health-checks/
# 2. Add to health check registry
# 3. Test with various scenarios

🧪 Testing

Component Testing

# Test component installation
npx claude-code-templates@latest --agent your-agent --dry-run
npx claude-code-templates@latest --command your-command --dry-run
npx claude-code-templates@latest --mcp your-mcp --dry-run

Template Testing

# Test template installation
npx claude-code-templates@latest --template your-template --dry-run

# Test with specific scenarios
npm start -- --language python --framework django --dry-run
npm start -- --language javascript --framework react --dry-run

Tool Testing

# Test analytics
npm run analytics:test

# Test chat monitor
npm run chats:test

# Test health check
npm run health-check:test

🤝 Contribution Process

1. Fork and Clone

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

2. Create Feature Branch

git checkout -b feature/your-contribution

3. Make Changes

  • Follow the guidelines above for your contribution type
  • Test thoroughly with real scenarios
  • Include comprehensive documentation

4. Test Changes

cd cli-tool
npm test
npm start -- --dry-run

5. Submit Pull Request

  • Clear description of changes
  • Screenshots for UI changes
  • Testing instructions
  • Reference related issues

🎯 What We're Looking For

High Priority Components

  • Security Agents - Security auditing, vulnerability scanning
  • Performance Commands - Optimization, profiling, monitoring
  • Cloud MCPs - AWS, Azure, GCP integrations
  • Framework Agents - React, Vue, Angular, Next.js specialists

High Priority Templates

  • Modern Frameworks - Svelte, SvelteKit, Astro, Qwik
  • Backend Frameworks - NestJS, Fastify, Hono, tRPC
  • Full-Stack - T3 Stack, create-remix-app, SvelteKit
  • Mobile - React Native, Expo, Flutter

Medium Priority Tools

  • Analytics Enhancements - Better visualizations, export options
  • Chat Monitor Features - Search, filtering, conversation history
  • Health Check Improvements - More diagnostic categories, fix suggestions

📞 Getting Help

Community Support

Quick Start Guides

  • Browse Components - aitmpl.com to see existing components
  • Component Examples - Check existing components for structure reference
  • Template Examples - Review successful templates for best practices

📄 License

By contributing to this project, you agree that your contributions will be licensed under the MIT License.

🙏 Recognition

All contributors are recognized in our:

  • GitHub Contributors page
  • Release Notes for significant contributions
  • Community Discussions for helpful contributions

Thank you for helping make Claude Code Templates better for everyone! 🚀