CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

Node.js CLI tool for managing Claude Code components (agents, commands, MCPs, hooks, settings) with a static website for browsing and installing components. The project includes Vercel API endpoints for download tracking and Discord integration.

Essential Commands

# Development
npm install                    # Install dependencies
npm test                       # Run tests
npm version patch|minor|major  # Bump version
npm publish                    # Publish to npm

# Component catalog
python scripts/generate_components_json.py  # Update docs/components.json

# API testing
cd api && npm test             # Test API endpoints before deploy
vercel --prod                  # Deploy to production

Security Guidelines

⛔ CRITICAL: NEVER Hardcode Secrets or IDs

NEVER write API keys, tokens, passwords, project IDs, org IDs, or any identifier in code. This includes Vercel project/org IDs, Supabase URLs, Discord IDs, database connection strings, and any other infrastructure identifier. ALL must go in .env.

// ❌ WRONG
const API_KEY = "AIzaSy...";

// ✅ CORRECT
const API_KEY = process.env.GOOGLE_API_KEY;

When creating scripts with API keys:

Use process.env (Node.js) or os.environ.get() (Python)
Load from .env file using dotenv
Add variable to .env.example with placeholder
Verify .env is in .gitignore

If you accidentally commit a secret:

Revoke the key IMMEDIATELY
Generate new key
Update .env
Old key is compromised forever (git history)

Component System

Component Types

Agents (600+) - AI specialists for development tasks Commands (200+) - Custom slash commands for workflows MCPs (55+) - External service integrations Settings (60+) - Claude Code configuration files Hooks (39+) - Automation triggers Templates (14+) - Complete project configurations

Installation Patterns

# Single component
npx claude-code-templates@latest --agent frontend-developer
npx claude-code-templates@latest --command setup-testing
npx claude-code-templates@latest --hook automation/simple-notifications

# Batch installation
npx claude-code-templates@latest --agent security-auditor --command security-audit --setting read-only-mode

# Interactive mode
npx claude-code-templates@latest

Component Development

Adding New Components

CRITICAL: Use the component-reviewer agent for ALL component changes

When adding or modifying components, you MUST use the component-reviewer subagent to validate the component before committing:

Use the component-reviewer agent to review [component-path]

Component Creation Workflow:

Create component file in cli-tool/components/{type}/{category}/{name}.md
Use descriptive hyphenated names (kebab-case)
Include clear descriptions and usage examples
REVIEW with component-reviewer agent (validates format, security, naming)
Fix any issues identified by the reviewer
Run python scripts/generate_components_json.py to update catalog

The component-reviewer agent checks:

✅ Valid YAML frontmatter and required fields
✅ Proper kebab-case naming conventions
✅ No hardcoded secrets (API keys, tokens, passwords)
✅ Relative paths only (no absolute paths)
✅ Supporting files exist (for hooks with scripts)
✅ Clear, specific descriptions
✅ Correct category placement
✅ Security best practices

Example Usage:

# After creating a new agent
Use the component-reviewer agent to review cli-tool/components/agents/development-team/react-expert.md

# Before committing hook changes
Use the component-reviewer agent to review cli-tool/components/hooks/git/prevent-force-push.json

# For PR reviews with multiple components
Use the component-reviewer agent to review all modified components in cli-tool/components/

The agent will provide prioritized feedback:

❌ Critical Issues: Must fix before merge (security, missing fields)
⚠️ Warnings: Should fix (clarity, best practices)
📋 Suggestions: Nice to have improvements

Statuslines with Python Scripts

Statuslines can reference Python scripts that are auto-downloaded to .claude/scripts/:

// In src/index.js:installIndividualSetting()
if (settingName.includes('statusline/')) {
  const pythonFileName = settingName.split('/')[1] + '.py';
  const pythonUrl = githubUrl.replace('.json', '.py');
  additionalFiles['.claude/scripts/' + pythonFileName] = {
    content: pythonContent,
    executable: true
  };
}

Publishing Workflow

# 1. Update component catalog
python scripts/generate_components_json.py

# 2. Run tests
npm test

# 3. Check current npm version and align local version
npm view claude-code-templates version  # check latest on registry
# Edit package.json version to be one patch above the registry version

# 4. Commit version bump and push
git add package.json && git commit -m "chore: Bump version to X.Y.Z"
git push origin main

# 5. Publish to npm (requires granular access token with "Bypass 2FA" enabled)
npm config set //registry.npmjs.org/:_authToken=YOUR_GRANULAR_TOKEN
npm publish
npm config delete //registry.npmjs.org/:_authToken  # always clean up after

# 6. Tag the release
git tag vX.Y.Z && git push origin vX.Y.Z

# 7. Deploy website
vercel --prod

npm Publishing Notes:

Classic npm tokens were revoked Dec 2025. Use granular access tokens from npmjs.com/settings/~/tokens
The token must have Read and Write permissions for claude-code-templates and "Bypass 2FA" enabled
Always remove the token from npm config after publishing (npm config delete)
The local package.json version may drift from npm if published from CI — always check npm view claude-code-templates version first
Never hardcode or commit tokens

API Architecture

Critical Endpoints

The /api directory contains Vercel Serverless Functions:

/api/track-download-supabase (CRITICAL)

Tracks component downloads for analytics
Used by CLI on every installation
Database: Supabase (component_downloads table)

/api/discord/interactions

Discord bot slash commands
Features: /search, /info, /install, /popular

/api/claude-code-check

Monitors Claude Code releases
Vercel Cron: every 30 minutes
Database: Neon (claude_code_versions, claude_code_changes, discord_notifications_log, monitoring_metadata tables)

Deployment Workflow

ALWAYS test before deploying:

# 1. Run API tests
cd api
npm test

# 2. If tests pass, deploy
cd ..
vercel --prod

# 3. Monitor logs
vercel logs aitmpl.com --follow

Environment Variables (Vercel)

# Supabase
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=xxx

# Neon Database
NEON_DATABASE_URL=postgresql://user:pass@host/db?sslmode=require

# Discord
DISCORD_APP_ID=xxx
DISCORD_BOT_TOKEN=xxx
DISCORD_PUBLIC_KEY=xxx
DISCORD_WEBHOOK_URL_CHANGELOG=https://discord.com/api/webhooks/xxx

Emergency Rollback

vercel ls                              # List deployments
vercel promote <previous-deployment>   # Rollback

Cloudflare Workers

The cloudflare-workers/ directory contains Cloudflare Worker projects that run independently from Vercel.

docs-monitor

Monitors https://code.claude.com/docs for changes every hour and sends Telegram notifications.

cd cloudflare-workers/docs-monitor
npm run dev          # Local dev
npx wrangler deploy  # Deploy

pulse (Weekly KPI Report)

Collects metrics from GitHub, Discord, Supabase, Vercel, and Google Analytics every Sunday at 14:00 UTC and sends a consolidated report via Telegram.

Architecture: Single index.js file (no npm dependencies at runtime). All source collectors, formatter, and Telegram sender in one file.

Cron: 0 14 * * 0 (Sundays 14:00 UTC / 11:00 AM Chile)

cd cloudflare-workers/pulse
npm run dev          # Local dev
npx wrangler deploy  # Deploy

# Manual trigger
curl -X POST https://pulse-weekly-report.SUBDOMAIN.workers.dev/trigger \
  -H "Authorization: Bearer $TRIGGER_SECRET"

# Test single source
curl -X POST "https://pulse-weekly-report.SUBDOMAIN.workers.dev/trigger?source=github" \
  -H "Authorization: Bearer $TRIGGER_SECRET"

# Dry run (no Telegram)
curl -X POST "https://pulse-weekly-report.SUBDOMAIN.workers.dev/trigger?send=false" \
  -H "Authorization: Bearer $TRIGGER_SECRET"

Secrets (Cloudflare):

TELEGRAM_BOT_TOKEN          # Shared with docs-monitor
TELEGRAM_CHAT_ID            # Shared with docs-monitor
GITHUB_TOKEN                # GitHub PAT (public_repo scope)
SUPABASE_URL                # Supabase project URL
SUPABASE_SERVICE_ROLE_KEY   # Supabase service role key
DISCORD_BOT_TOKEN           # Discord bot token
DISCORD_GUILD_ID            # Discord server ID
VERCEL_TOKEN                # Vercel personal access token (optional)
VERCEL_PROJECT_ID           # Vercel project ID (optional)
TRIGGER_SECRET              # For manual /trigger endpoint
GA_PROPERTY_ID              # GA4 property ID (optional)
GA_SERVICE_ACCOUNT_JSON     # Base64 service account (optional)

Graceful degradation: Each source catches its own errors. Missing secrets or API failures show ⚠️ Unavailable instead of crashing the report.

Dashboard (app.aitmpl.com)

Astro + React + Tailwind dashboard deployed at https://app.aitmpl.com. Clerk auth for user collections. Source lives in dashboard/.

Architecture

Framework: Astro 5 with React islands, Tailwind v4, output: 'server'
Auth: Clerk (window.Clerk global, no ClerkProvider per island)
Data: Fetches from https://www.aitmpl.com/components.json at runtime (NOT bundled)
API proxy: dashboard/src/pages/api/[...path].ts proxies to localhost:3000 in dev, https://www.aitmpl.com in prod

Vercel Project Setup

Two separate Vercel projects deploy from the same repo:

Project	Domain	Root Directory
`aitmpl`	`www.aitmpl.com`	`/` (root)
`aitmpl-dashboard`	`app.aitmpl.com`	`dashboard`

Each directory has its own .vercel/project.json with the correct project ID. Do NOT mix them up.

Deployment

ALWAYS use the deployer agent (.claude/agents/deployer.md) for all deployments. It runs pre-deploy checks (auth, git status, API tests) and handles the full pipeline safely. Never deploy manually.

npm run deploy:site        # Deploy www.aitmpl.com (main site + API)
npm run deploy:dashboard   # Deploy app.aitmpl.com (Astro dashboard)
npm run deploy:all         # Deploy both

CI/CD: Pushes to main auto-deploy via GitHub Actions (.github/workflows/deploy.yml):

Changes in docs/, api/, or vercel.json trigger site deploy
Changes in dashboard/ trigger dashboard deploy

Required GitHub Secrets (Settings > Secrets > Actions):

VERCEL_TOKEN — Vercel personal access token
VERCEL_ORG_ID — Vercel org/team ID
VERCEL_SITE_PROJECT_ID — Project ID for www.aitmpl.com
VERCEL_DASHBOARD_PROJECT_ID — Project ID for app.aitmpl.com

Dashboard Environment Variables (Vercel)

PUBLIC_CLERK_PUBLISHABLE_KEY=xxx           # Clerk public key
CLERK_SECRET_KEY=xxx                        # Clerk secret key
PUBLIC_COMPONENTS_JSON_URL=https://www.aitmpl.com/components.json  # MUST use www

Known Issues & Solutions

Node v24 breaks fs.writeFileSync on Vercel

Node v24 has a bug with writeFileSync in Vercel's build environment
Solution: Dashboard project is pinned to Node 22.x (set via Vercel API/dashboard)

CORS: Always use www.aitmpl.com for cross-origin fetches

aitmpl.com (bare domain) 307-redirects to www.aitmpl.com
The redirect response has NO CORS headers, which blocks browser fetches from app.aitmpl.com
www.aitmpl.com serves the actual response WITH Access-Control-Allow-Origin: *
The PUBLIC_COMPONENTS_JSON_URL env var MUST point to https://www.aitmpl.com/... (not https://aitmpl.com/...)
CORS headers are configured in the root vercel.json under headers

Local Development

cd dashboard
npm install
npx astro dev --port 4321   # Dashboard at http://localhost:4321
# In another terminal, for API proxy:
node api/dev-server.js       # API at http://localhost:3000

Website Architecture (docs/)

Static website at https://aitmpl.com for browsing components.

Key Files

docs/components.json - Component catalog (generated, ~2MB)
docs/index.html - Main component browser
docs/blog/ - Blog articles
docs/js/ - Vanilla JavaScript (data-loader, search, cart)

Data Flow

scripts/generate_components_json.py scans cli-tool/components/
Generates docs/components.json with embedded content
Website loads JSON and renders component cards
Download tracking via /api/track-download-supabase

Blog Article Creation

Use the CLI skill to create blog articles:

/create-blog-article @cli-tool/components/{type}/{category}/{name}.json

This automatically:

Generates AI cover image
Creates HTML with SEO optimization
Updates docs/blog/blog-articles.json

Code Standards

Path Handling

Use relative paths: .claude/scripts/, .claude/hooks/
Never hardcode absolute paths or home directories
Use path.join() for cross-platform compatibility

Naming Conventions

Files: kebab-case.js, PascalCase.js (for classes)
Functions/Variables: camelCase
Constants: UPPER_SNAKE_CASE
Components: hyphenated-names

Error Handling

Use try/catch for async operations
Provide helpful error messages
Log errors with context
Implement fallback mechanisms

Testing

npm test                 # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report
cd api && npm test      # Test API endpoints

Aim for 70%+ test coverage. Test critical paths and error handling.

Common Issues

API endpoint returns 404 after deploy

Serverless functions must be in /api/ directory
Use format: /api/function-name.js or /api/folder/index.js

Download tracking not working

Check Vercel logs: vercel logs aitmpl.com --follow
Verify environment variables in Vercel dashboard
Test endpoint manually with curl

Components not updating on website

Run python scripts/generate_components_json.py
Clear browser cache
Check docs/components.json file size

Important Notes

Component catalog: Always regenerate after adding/modifying components
API tests: Required before production deploy (breaks download tracking)
Secrets: Never commit API keys (use environment variables)
Paths: Use relative paths for all project files
Backwards compatibility: Don't break existing component installations

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md

Project Overview

Essential Commands

Security Guidelines

⛔ CRITICAL: NEVER Hardcode Secrets or IDs

Component System

Component Types

Installation Patterns

Component Development

Adding New Components

Statuslines with Python Scripts

Publishing Workflow

API Architecture

Critical Endpoints

Deployment Workflow

Environment Variables (Vercel)

Emergency Rollback

Cloudflare Workers

docs-monitor

pulse (Weekly KPI Report)

Dashboard (app.aitmpl.com)

Architecture

Vercel Project Setup

Deployment

Dashboard Environment Variables (Vercel)

Known Issues & Solutions

Local Development

Website Architecture (docs/)

Key Files

Data Flow

Blog Article Creation

Code Standards

Path Handling

Naming Conventions

Error Handling

Testing

Common Issues

Important Notes