Installation Guide

This guide covers everything you need to know about installing Claude Code Templates, from basic usage to advanced configuration and batch installation.

Prerequisites

Required Software

Node.js 14+: Required to run the CLI tool
Claude Code: Anthropic’s Claude Code IDE (download)
Git (optional): For version control integration

Claude Code Templates works with any project type. The CLI automatically detects your project structure and recommends appropriate components.

Basic Installation

Install via npx (Recommended)

No installation required - run directly with npx:

npx claude-code-templates@latest

The @latest tag ensures you always get the newest components:

Package Information

Package: claude-code-templates
Version: 1.28.16
NPM: https://www.npmjs.com/package/claude-code-templates
Short alias: cct

Install Globally

For frequent use, install globally:

npm install -g claude-code-templates

# Then run anywhere:
claude-code-templates
# or
cct

Global installation may use an older version unless you update regularly:

npm update -g claude-code-templates

Component Types

Claude Code Templates provides six types of components:

🤖 Agents (400+)

What they are: AI specialists with domain-specific knowledge and context. Location: .claude/agents/ Installation:

npx claude-code-templates@latest --agent development-team/frontend-developer

Usage: Reference in Claude Code with @agent-name Examples:

development-team/frontend-developer - Expert in React, Vue, Angular
security/security-auditor - Security analysis and vulnerability detection
devops-infrastructure/kubernetes-expert - Container orchestration specialist
data-ai/machine-learning-engineer - ML model development and training

Categories:

Development Team (Frontend, Backend, Fullstack)
Development Tools (Code Review, Refactoring)
Security (Auditing, Penetration Testing)
DevOps & Infrastructure (Docker, Kubernetes, AWS)
Data & AI (ML, Data Science, Analytics)
Documentation (Technical Writing, API Docs)
Testing & QA (Unit Testing, E2E Testing)
Database (PostgreSQL, MongoDB, Redis)
API & GraphQL (REST, GraphQL, API Design)
And 20+ more categories…

⚡ Commands (225+)

What they are: Custom slash commands for automated workflows. Location: .claude/commands/ Installation:

npx claude-code-templates@latest --command testing/generate-tests

Usage: Type /command-name in Claude Code Examples:

/generate-tests - Generate unit tests for selected code
/optimize-bundle - Analyze and optimize bundle size
/check-security - Run security audit on dependencies
/setup-ci - Configure CI/CD pipeline
/refactor-code - Suggest refactoring improvements

Categories:

Testing (Unit Tests, E2E Tests, Coverage)
Performance (Bundle Optimization, Profiling)
Security (Vulnerability Scanning, SAST)
Documentation (README, API Docs, Changelog)
Code Quality (Linting, Formatting, Review)
Deployment (CI/CD, Docker, Cloud)

🔌 MCPs (65+)

What they are: Model Context Protocol integrations for external services. Location: .claude/mcps/ Installation:

npx claude-code-templates@latest --mcp development/github-integration

Usage: Claude Code connects automatically on startup Examples:

development/github-integration - GitHub API access
database/postgresql-integration - PostgreSQL queries
cloud/aws-integration - AWS service management
payment/stripe-integration - Stripe API integration
ai/openai-integration - OpenAI API access

Categories:

Development (GitHub, GitLab, Bitbucket)
Database (PostgreSQL, MySQL, MongoDB, Redis)
Cloud (AWS, Azure, GCP, Vercel)
Payment (Stripe, PayPal)
AI & ML (OpenAI, Anthropic, Hugging Face)
Communication (Slack, Discord, Telegram)

MCPs often require API credentials. Check component documentation for required environment variables.

⚙️ Settings (60+)

What they are: Claude Code configuration presets. Location: .claude/settings/ Installation:

npx claude-code-templates@latest --setting performance/mcp-timeouts

Examples:

performance/mcp-timeouts - Optimize MCP connection timeouts
memory/large-projects - Memory settings for large codebases
output/verbose-logging - Enable detailed logging
read-only-mode - Prevent file modifications

🪝 Hooks (45+)

What they are: Automation triggers for development workflows. Location: .claude/hooks/ Installation:

npx claude-code-templates@latest --hook git/pre-commit-validation

Examples:

git/pre-commit-validation - Validate code before commits
automation/simple-notifications - Send notifications on events
deployment/post-deploy-check - Verify deployments

🎨 Skills (300+)

What they are: Reusable capabilities with progressive disclosure. Location: .claude/skills/ Installation:

npx claude-code-templates@latest --skill pdf-processing

Examples:

pdf-processing - Generate and manipulate PDFs
excel-automation - Automate Excel operations
scientific-computing - Scientific computation tools

Installation Methods

Interactive Mode

Launch the interactive CLI to browse and select components:

npx claude-code-templates@latest

Workflow:

Main menu appears
Select “Project Setup”
Choose component type (Agent, Command, MCP, etc.)
Browse categories
Select specific components
Confirm installation

Interactive mode is great for discovering new components and learning what’s available.

Direct Installation

Install specific components directly:

Single Component

# Install one agent
npx claude-code-templates@latest --agent development-team/frontend-developer

# Install one command
npx claude-code-templates@latest --command testing/generate-tests

# Install one MCP
npx claude-code-templates@latest --mcp development/github-integration

Batch Installation

Install multiple components in one command:

Multiple Components

npx claude-code-templates@latest \
  --agent development-team/frontend-developer \
  --agent development-team/react-expert \
  --command testing/generate-tests \
  --command performance/optimize-bundle \
  --mcp development/github-integration \
  --hook git/pre-commit-validation \
  --setting performance/mcp-timeouts \
  --yes

You can install multiple of the same type by repeating the flag:

--agent security-auditor --agent code-reviewer --agent react-expert

Skip Prompts

Use --yes to skip all confirmation prompts:

npx claude-code-templates@latest \
  --agent development-team/frontend-developer \
  --yes

Perfect for:

Automated scripts
CI/CD pipelines
Team onboarding scripts
Docker containers

Advanced Installation

Install to Specific Directory

By default, components install to the current directory’s .claude/ folder. Change the target:

npx claude-code-templates@latest \
  --directory /path/to/project \
  --agent frontend-developer

Dry Run

See what would be installed without actually installing:

npx claude-code-templates@latest \
  --agent frontend-developer \
  --dry-run

Output shows:

Files that would be created
Directories that would be modified
Configuration changes

Comma-Separated Values

Install multiple components of the same type with commas:

npx claude-code-templates@latest \
  --agent "development-team/frontend-developer,security/security-auditor,devops-infrastructure/kubernetes-expert" \
  --yes

Workflow Installation

Install complete workflows from templates:

npx claude-code-templates@latest --workflow "#react-testing-workflow"

Workflows are pre-configured sets of components that work together.

Project Templates

For new projects, use complete project templates:

JavaScript/TypeScript

npx claude-code-templates@latest --template javascript-typescript --yes

Python

npx claude-code-templates@latest --template python --yes

Ruby

npx claude-code-templates@latest --template ruby --yes

Common (Language Agnostic)

npx claude-code-templates@latest --template common --yes

Templates include:

Language-specific agents
Common commands
Recommended MCPs
Standard hooks
Configuration presets

Configuration

Component Configuration

After installation, components are configured in .claude/:

Directory Structure

.claude/
├── agents/
│   ├── frontend-developer.md
│   └── react-expert.md
├── commands/
│   ├── generate-tests.json
│   └── optimize-bundle.json
├── hooks/
│   └── pre-commit-validation.json
├── mcps/
│   └── github-integration.json
├── settings/
│   └── mcp-timeouts.json
└── config.json

Environment Variables

Some components require environment variables:

.env

# GitHub MCP
GITHUB_TOKEN=ghp_your_token_here

# PostgreSQL MCP
DATABASE_URL=postgresql://user:pass@localhost:5432/db

# AWS MCP
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1

# OpenAI MCP
OPENAI_API_KEY=sk-...

Never commit .env files to version control. Add to .gitignore:

echo ".env" >> .gitignore

Python Command Configuration

On Windows, the CLI automatically detects and uses the correct Python command:

Windows: python or py
Unix/Linux/Mac: python3

Statusline settings with Python scripts work automatically across platforms.

CLI Reference

Complete CLI options:

Command Line Options

claude-code-templates [options]

Options:
  -V, --version                    Output version number
  -h, --help                       Display help
  -t, --template <template>        Project template (common, javascript-typescript, python, ruby)
  -d, --directory <directory>      Target directory (default: current)
  -y, --yes                        Skip prompts and use defaults
  --dry-run                        Show what would be installed
  
Component Installation:
  --agent <agent>                  Install agent (comma-separated)
  --command <command>              Install command (comma-separated)
  --mcp <mcp>                      Install MCP (comma-separated)
  --setting <setting>              Install setting (comma-separated)
  --hook <hook>                    Install hook (comma-separated)
  --skill <skill>                  Install skill (comma-separated)
  --workflow <workflow>            Install workflow from hash
  
Tools & Utilities:
  --analytics                      Launch analytics dashboard
  --chats                          Launch conversation monitor
  --agents                         Launch agents dashboard
  --plugins                        Launch plugin dashboard
  --skills-manager                 Launch skills dashboard
  --teams                          Launch agent teams dashboard
  --health-check                   Run health diagnostics
  --tunnel                         Enable Cloudflare Tunnel (with --analytics or --chats)
  --verbose                        Enable verbose logging
  
Statistics & Analysis:
  --command-stats                  Analyze command usage
  --hook-stats                     Analyze hook usage
  --mcp-stats                      Analyze MCP usage
  
Global Agents:
  --create-agent <name>            Create global agent
  --list-agents                    List global agents
  --remove-agent <name>            Remove global agent
  --update-agent <name>            Update global agent
  
Advanced:
  --sandbox <provider>             Execute in sandbox (e2b)
  --studio                         Launch Claude Code Studio
  --clone-session <url>            Import shared session
  --prompt <prompt>                Execute prompt after install

Verification

Health Check

Verify installation with the health check tool:

npx claude-code-templates@latest --health-check

Checks:

✓ Claude Code installation
✓ Configuration file validity
✓ Component integrity
✓ Dependency availability
✓ Environment variable configuration
✓ File permissions

Manual Verification

Check installed components:

# List all components
ls -la .claude/

# Check agents
ls .claude/agents/

# Check commands
ls .claude/commands/

# Verify configuration
cat .claude/config.json

Troubleshooting

Installation fails with permission errors

On Unix systems, ensure you have write permissions:

# Check permissions
ls -la

# Fix permissions if needed
chmod +w .

# Or install to home directory
npx claude-code-templates@latest --directory ~/my-project

Components not appearing in Claude Code

Make sure Claude Code is running in the correct directory:
pwd ls .claude/
Restart Claude Code to reload configuration
Check Claude Code output for errors

Run health check:

npx claude-code-templates@latest --health-check

MCP connection failures

Check required environment variables:
cat .env
Verify credentials are valid

Check MCP configuration:

cat .claude/mcps/github-integration.json

Look for error messages in Claude Code output
Some MCPs require external services to be running

npx command not found

Install Node.js 14 or higher:

# Check current version
node --version

# Install from https://nodejs.org
# Or use nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Python statusline not working

Check Python installation:

python --version
python3 --version
py --version

Verify script permissions:
chmod +x .claude/scripts/*.py
Check script path in statusline configuration
The CLI automatically handles platform differences

Global agent installation fails

Global agents require additional setup:

# Create global agent
npx claude-code-templates@latest --create-agent my-agent

# List agents
npx claude-code-templates@latest --list-agents

# Ensure proper permissions
chmod +x ~/.claude-code-templates/agents/*

Next Steps

Browse Components

Explore 900+ components in the interactive catalog.

CLI Reference

Complete documentation for all CLI commands and options.

Analytics Dashboard

Monitor your Claude Code sessions in real-time.

Contributing

Add your own components to the collection.

Need help?

Join our GitHub Discussions to ask questions and get support from the community.

​Installation Guide

​Prerequisites

Required Software

​Basic Installation

​Install via npx (Recommended)

​Install Globally

​Component Types

​🤖 Agents (400+)

​⚡ Commands (225+)

​🔌 MCPs (65+)

​⚙️ Settings (60+)

​🪝 Hooks (45+)

​🎨 Skills (300+)

​Installation Methods

​Interactive Mode

​Direct Installation

​Batch Installation

​Skip Prompts

​Advanced Installation

​Install to Specific Directory

​Dry Run

​Comma-Separated Values

​Workflow Installation

​Project Templates

​Configuration

​Component Configuration

​Environment Variables

​Python Command Configuration

​CLI Reference

​Verification

​Health Check

​Manual Verification

​Troubleshooting

​Next Steps

Browse Components

CLI Reference

Analytics Dashboard

Contributing

Need help?

Installation Guide

Prerequisites

Basic Installation

Install via npx (Recommended)

Install Globally

Component Types

🤖 Agents (400+)

⚡ Commands (225+)

🔌 MCPs (65+)

⚙️ Settings (60+)

🪝 Hooks (45+)

🎨 Skills (300+)

Installation Methods

Interactive Mode

Direct Installation

Batch Installation

Skip Prompts

Advanced Installation

Install to Specific Directory

Dry Run

Comma-Separated Values

Workflow Installation

Project Templates

Configuration

Component Configuration

Environment Variables

Python Command Configuration

CLI Reference

Verification

Health Check

Manual Verification

Troubleshooting

Next Steps