# Repository: davila7/claude-code-templates # Stars: 24675 ## CLAUDE.md # 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 ```bash # 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`. ```javascript // ❌ WRONG const API_KEY = "AIzaSy..."; // ✅ CORRECT const API_KEY = process.env.GOOGLE_API_KEY; ``` **When creating scripts with API keys:** 1. Use `process.env` (Node.js) or `os.environ.get()` (Python) 2. Load from `.env` file using `dotenv` 3. Add variable to `.env.example` with placeholder 4. Verify `.env` is in `.gitignore` **If you accidentally commit a secret:** 1. Revoke the key IMMEDIATELY 2. Generate new key 3. Update `.env` 4. 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 ```bash # 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:** 1. Create component file in `cli-tool/components/{type}/{category}/{name}.md` 2. Use descriptive hyphenated names (kebab-case) 3. Include clear descriptions and usage examples 4. **REVIEW with component-reviewer agent** (validates format, security, naming) 5. Fix any issues identified by the reviewer 6. 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/`: ```javascript // 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 ```bash # 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](https://www.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 API endpoints live as Astro API routes in `dashboard/src/pages/api/`: **`/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) ### Shared API Libraries - `dashboard/src/lib/api/cors.ts` — CORS headers, `corsResponse()`, `jsonResponse()` - `dashboard/src/lib/api/neon.ts` — Neon client factory - `dashboard/src/lib/api/auth.ts` — Clerk JWT verification - `dashboard/src/lib/api/changelog-parser.ts` — Claude Code changelog parser ### Emergency Rollback ```bash vercel ls # List deployments vercel promote # 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. ```bash 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) ```bash 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):** ```bash 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 (www.aitmpl.com) Astro + React + Tailwind dashboard serving both `www.aitmpl.com` and `app.aitmpl.com`. Clerk auth for user collections. Source lives in `dashboard/`. All API endpoints are Astro API routes in the same project. ### Architecture - **Framework**: Astro 5 with React islands, Tailwind v4, `output: 'server'` - **Auth**: Clerk (`window.Clerk` global, no ClerkProvider per island) - **Data**: `components.json` and `trending-data.json` served from `dashboard/public/` (same-origin) - **APIs**: All endpoints in `dashboard/src/pages/api/` (Astro API routes, no separate serverless project) ### Featured Pages (`/featured/[slug]`) Featured partner integrations shown on the dashboard homepage. Two files to edit: **`dashboard/src/lib/constants.ts`** — `FEATURED_ITEMS` array. Each entry has: - `name`, `description`, `logo`, `url` (`/featured/slug`), `tag`, `tagColor`, `category` - `ctaLabel`, `ctaUrl`, `websiteUrl` - `installCommand` — shown in the sidebar Quick Install box - `metadata` — key/value pairs shown in the Details sidebar (e.g. `Components: '8'`) - `links` — sidebar links list **`dashboard/src/pages/featured/[slug].astro`** — Content for each slug rendered via `{slug === 'brightdata' && (...)}` blocks. Each block contains the full HTML content for that partner page. **When adding a skill to a featured page:** 1. Add a new card `
` inside the Skills Layer section of the relevant `{slug === '...'}` block 2. Update `installCommand` in `constants.ts` to include the new skill 3. Increment `metadata.Components` count in `constants.ts` Current featured slugs: `brightdata`, `neon-instagres`, `claudekit`, `braingrid` ### Vercel Project Setup Single Vercel project serves all domains: | Project | Domains | Root Directory | |---------|---------|----------------| | `aitmpl-dashboard` | `www.aitmpl.com`, `aitmpl.com` (redirect), `app.aitmpl.com` | `dashboard` | The legacy root project (`aitmpl`) is archived — only its `.vercel.app` subdomain remains. ### 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. ```bash npm run deploy # Deploy www + app.aitmpl.com npm run deploy:dashboard # Same as above ``` **CI/CD**: Pushes to `main` auto-deploy via GitHub Actions (`.github/workflows/deploy.yml`): - Changes in `dashboard/**` trigger deploy **Required GitHub Secrets** (Settings > Secrets > Actions): - `VERCEL_TOKEN` — Vercel personal access token - `VERCEL_ORG_ID` — Vercel org/team ID - `VERCEL_DASHBOARD_PROJECT_ID` — Project ID for aitmpl-dashboard ### Environment Variables (Vercel) ```bash # Clerk PUBLIC_CLERK_PUBLISHABLE_KEY=xxx CLERK_SECRET_KEY=xxx # Data PUBLIC_COMPONENTS_JSON_URL=/components.json # GitHub OAuth PUBLIC_GITHUB_CLIENT_ID=xxx GITHUB_CLIENT_SECRET=xxx # Supabase (download tracking) 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 ``` ### 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) **Vercel CLI ignores local `.vercel/project.json`** - The CLI often resolves to the parent directory's project. Use `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` env vars to force the correct project. ### Local Development ```bash cd dashboard npm install npx astro dev --port 4321 # Dashboard + APIs at http://localhost:4321 ``` ## Data Files ### Component Catalog - `docs/components.json` — Generated catalog (source of truth) - `dashboard/public/components.json` — Copy served by the dashboard - `dashboard/public/trending-data.json` — Trending/download stats ### Data Flow 1. `scripts/generate_components_json.py` scans `cli-tool/components/` 2. Generates `docs/components.json` with embedded content 3. Copy to `dashboard/public/components.json` for the dashboard to serve 4. Dashboard loads JSON and renders component cards 5. Download tracking via `/api/track-download-supabase` ### Legacy Static Site (docs/) The `docs/` directory contains the old static HTML site (no longer deployed to www). Blog articles in `docs/blog/` are still referenced externally. ### Blog Article Creation Use the CLI skill to create blog articles: ```bash /create-blog-article @cli-tool/components/{type}/{category}/{name}.json ``` This automatically: 1. Generates AI cover image 2. Creates HTML with SEO optimization 3. 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 ```bash npm test # Run all tests npm run test:watch # Watch mode npm run test:coverage # Coverage report ``` Aim for 70%+ test coverage. Test critical paths and error handling. ## Common Issues **API endpoint returns 404 after deploy** - API routes must be in `dashboard/src/pages/api/` as Astro API routes - Export named HTTP methods: `export const POST: APIRoute`, `export const GET: APIRoute` **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` - Copy `docs/components.json` to `dashboard/public/components.json` - Deploy and clear browser cache ## 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 ## README.md [![npm version](https://img.shields.io/npm/v/claude-code-templates.svg)](https://www.npmjs.com/package/claude-code-templates) [![npm downloads](https://img.shields.io/npm/dt/claude-code-templates.svg)](https://www.npmjs.com/package/claude-code-templates) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) [![Sponsored by Z.AI](https://img.shields.io/badge/Sponsored%20by-Z.AI-2563eb?style=flat&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTEyIDJMMiAyMkgyMkwxMiAyWiIgZmlsbD0id2hpdGUiLz4KPC9zdmc+)](https://z.ai/subscribe?ic=8JVLJQFSKB&utm_source=github&utm_medium=badge&utm_campaign=readme) [![Claude for Open Source](https://img.shields.io/badge/Claude-Open%20Source%20Program-D97757?style=flat&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIzIiBmaWxsPSJ3aGl0ZSIvPjwvc3ZnPg==)](https://claude.com/contact-sales/claude-for-oss) [![Neon Open Source Program](https://img.shields.io/badge/Neon-Open%20Source%20Program-00E599?style=flat)](https://get.neon.com/4eCjZDz) [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?style=flat&logo=buy-me-a-coffee)](https://buymeacoffee.com/daniavila) [![GitHub stars](https://img.shields.io/github/stars/davila7/claude-code-templates.svg?style=social&label=Star)](https://github.com/davila7/claude-code-templates)

davila7%2Fclaude-code-templates | Trendshift

Vercel OSS Program    Neon Open Source Program    Claude for Open Source

--- > **🧪 NEW: Dashboard** — Explore components, manage collections, and track installations at **[www.aitmpl.com](https://www.aitmpl.com)**. Currently in beta — feedback welcome! # Claude Code Templates ([aitmpl.com](https://aitmpl.com)) **Ready-to-use configurations for Anthropic's Claude Code.** A comprehensive collection of AI agents, custom commands, settings, hooks, external integrations (MCPs), and project templates to enhance your development workflow. ## Browse & Install Components and Templates **[Browse All Templates](https://aitmpl.com)** - Interactive web interface to explore and install 100+ agents, commands, settings, hooks, and MCPs. Screenshot 2025-08-19 at 08 09 24 ## 🚀 Quick Installation ```bash # Install a complete development stack npx claude-code-templates@latest --agent development-team/frontend-developer --command testing/generate-tests --mcp development/github-integration --yes # Browse and install interactively npx claude-code-templates@latest # Install specific components npx claude-code-templates@latest --agent development-tools/code-reviewer --yes npx claude-code-templates@latest --command performance/optimize-bundle --yes npx claude-code-templates@latest --setting performance/mcp-timeouts --yes npx claude-code-templates@latest --hook git/pre-commit-validation --yes npx claude-code-templates@latest --mcp database/postgresql-integration --yes ``` ## What You Get | Component | Description | Examples | |-----------|-------------|----------| | **🤖 Agents** | AI specialists for specific domains | Security auditor, React performance optimizer, database architect | | **⚡ Commands** | Custom slash commands | `/generate-tests`, `/optimize-bundle`, `/check-security` | | **🔌 MCPs** | External service integrations | GitHub, PostgreSQL, Stripe, AWS, OpenAI | | **⚙️ Settings** | Claude Code configurations | Timeouts, memory settings, output styles | | **🪝 Hooks** | Automation triggers | Pre-commit validation, post-completion actions | | **🎨 Skills** | Reusable capabilities with progressive disclosure | PDF processing, Excel automation, custom workflows | ## 🛠️ Additional Tools Beyond the template catalog, Claude Code Templates includes powerful development tools: ### 📊 Claude Code Analytics Monitor your AI-powered development sessions in real-time with live state detection and performance metrics. ```bash npx claude-code-templates@latest --analytics ``` ### 💬 Conversation Monitor Mobile-optimized interface to view Claude responses in real-time with secure remote access. ```bash # Local access npx claude-code-templates@latest --chats # Secure remote access via Cloudflare Tunnel npx claude-code-templates@latest --chats --tunnel ``` ### 🔍 Health Check Comprehensive diagnostics to ensure your Claude Code installation is optimized. ```bash npx claude-code-templates@latest --health-check ``` ### 🔌 Plugin Dashboard View marketplaces, installed plugins, and manage permissions from a unified interface. ```bash npx claude-code-templates@latest --plugins ``` ## 📖 Documentation **[📚 docs.aitmpl.com](https://docs.aitmpl.com/)** - Complete guides, examples, and API reference for all components and tools. ## Contributing We welcome contributions! **[Browse existing templates](https://aitmpl.com)** to see what's available, then check our [contributing guidelines](CONTRIBUTING.md) to add your own agents, commands, MCPs, settings, or hooks. **Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.** ## Attribution This collection includes components from multiple sources: **Scientific Skills:** - **[K-Dense-AI/claude-scientific-skills](https://github.com/K-Dense-AI/claude-scientific-skills)** by K-Dense Inc. - MIT License (139 scientific skills for biology, chemistry, medicine, and computational research) **Official Anthropic:** - **[anthropics/skills](https://github.com/anthropics/skills)** - Official Anthropic skills (21 skills) - **[anthropics/claude-code](https://github.com/anthropics/claude-code)** - Development guides and examples (10 skills) **Community Skills & Agents:** - **[obra/superpowers](https://github.com/obra/superpowers)** by Jesse Obra - MIT License (14 workflow skills) - **[alirezarezvani/claude-skills](https://github.com/alirezarezvani/claude-skills)** by Alireza Rezvani - MIT License (36 professional role skills) - **[wshobson/agents](https://github.com/wshobson/agents)** by wshobson - MIT License (48 agents) - **NerdyChefsAI Skills** - Community contribution - MIT License (specialized enterprise skills) **Commands & Tools:** - **[awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code)** by hesreallyhim - CC0 1.0 Universal (21 commands) - **[awesome-claude-skills](https://github.com/mehdi-lamrani/awesome-claude-skills)** - Apache 2.0 (community skills) - **move-code-quality-skill** - MIT License - **cocoindex-claude** - Apache 2.0 Each of these resources retains its **original license and attribution**, as defined by their respective authors. We respect and credit all original creators for their work and contributions to the Claude ecosystem. ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🔗 Links - **🌐 Browse Templates**: [aitmpl.com](https://aitmpl.com) - **📚 Documentation**: [docs.aitmpl.com](https://docs.aitmpl.com) - **💬 Community**: [GitHub Discussions](https://github.com/davila7/claude-code-templates/discussions) - **🐛 Issues**: [GitHub Issues](https://github.com/davila7/claude-code-templates/issues) ## Stargazers over time [![Stargazers over time](https://starchart.cc/davila7/claude-code-templates.svg?variant=adaptive)](https://starchart.cc/davila7/claude-code-templates) --- **⭐ Found this useful? Give us a star to support the project!** [![Buy Me A Coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&slug=daniavila&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://buymeacoffee.com/daniavila)