claude-code-templates 1.19.1 → 1.20.0

package/README.md

@@ -28,6 +28,7 @@ npx claude-code-templates@latest --health-check
 - **📊 Real-time Analytics** - Monitor Claude Code sessions with live state detection and performance metrics
 - **🔍 Health Check** - Comprehensive system validation with actionable recommendations
 - **🧩 Individual Components** - Install specialized agents, commands, and MCPs individually
+- **🌍 Global Agents** - Create AI agents accessible from anywhere using Claude Code SDK
 
 ## 🎯 What You Get
 
@@ -49,6 +50,51 @@ npx claude-code-templates@latest --health-check
 | **Go** | Gin, Echo, Fiber | 🚧 Coming Soon |
 | **Rust** | Axum, Warp, Actix | 🚧 Coming Soon |
 
+## 🌍 Global Agents (Claude Code SDK Integration)
+
+Create AI agents that can be executed from anywhere using the Claude Code SDK:
+
+```bash
+# Create a global agent (one-time setup)
+npx claude-code-templates@latest --create-agent customer-support
+
+# Use the agent from anywhere
+customer-support "Help me with ticket #12345"
+sre-logs "Analyze error patterns in app.log"  
+code-reviewer "Review this PR for security issues"
+```
+
+### Available Global Agents
+
+| Agent | Usage | Description |
+|-------|-------|-------------|
+| `customer-support` | `customer-support "query"` | AI customer support specialist |
+| `api-security-audit` | `api-security-audit "analyze endpoints"` | Security auditing for APIs |
+| `react-performance-optimization` | `react-performance-optimization "optimize components"` | React performance expert |
+| `database-optimization` | `database-optimization "improve queries"` | Database performance tuning |
+
+### Global Agent Management
+
+```bash
+# List installed global agents
+npx claude-code-templates@latest --list-agents
+
+# Update an agent to latest version
+npx claude-code-templates@latest --update-agent customer-support
+
+# Remove an agent
+npx claude-code-templates@latest --remove-agent customer-support
+```
+
+### How It Works
+
+1. **Download Agent**: Fetches the latest agent from GitHub
+2. **Generate Executable**: Creates a Node.js script that calls Claude Code SDK
+3. **Add to PATH**: Makes the agent available globally in your shell
+4. **Ready to Use**: Execute `agent-name "your prompt"` from any directory
+
+The agents use the Claude Code SDK internally to provide specialized AI assistance with domain-specific knowledge and best practices.
+
 ## 📖 Documentation
 
 **[📚 Complete Documentation](https://docs.aitmpl.com/)** - Comprehensive guides, examples, and API reference

package/bin/create-claude-config.js

@@ -41,7 +41,7 @@ console.log(
 
 program
   .name('create-claude-config')
-  .description('Setup Claude Code configurations for different programming languages')
+  .description('Setup Claude Code configurations and create global AI agents powered by Claude Code SDK')
   .version(require('../package.json').version)
   .option('-l, --language <language>', 'specify programming language (deprecated, use --template)')
   .option('-f, --framework <framework>', 'specify framework (deprecated, use --template)')
@@ -66,6 +66,10 @@ program
   .option('--hook <hook>', 'install specific hook component (supports comma-separated values)')
   .option('--workflow <workflow>', 'install workflow from hash (#hash) OR workflow YAML (base64 encoded) when used with --agent/--command/--mcp')
   .option('--prompt <prompt>', 'execute the provided prompt in Claude Code after installation')
+  .option('--create-agent <agent>', 'create a global agent accessible from anywhere (e.g., customer-support)')
+  .option('--list-agents', 'list all installed global agents')
+  .option('--remove-agent <agent>', 'remove a global agent')
+  .option('--update-agent <agent>', 'update a global agent to the latest version')
   .action(async (options) => {
     try {
       await createClaudeConfig(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-templates",
-  "version": "1.19.1",
+  "version": "1.20.0",
   "description": "CLI tool to setup Claude Code configurations with framework-specific commands, automation hooks and MCP Servers for your projects",
   "main": "src/index.js",
   "bin": {

package/src/index.js

@@ -16,6 +16,7 @@ const { runAnalytics } = require('./analytics');
 const { startChatsMobile } = require('./chats-mobile');
 const { runHealthCheck } = require('./health-check');
 const { trackingService } = require('./tracking-service');
+const { createGlobalAgent, listGlobalAgents, removeGlobalAgent, updateGlobalAgent } = require('./sdk/global-agent-manager');
 
 async function showMainMenu() {
   console.log('');
@@ -130,6 +131,30 @@ async function createClaudeConfig(options = {}) {
     return;
   }
   
+  // Handle global agent creation
+  if (options.createAgent) {
+    await createGlobalAgent(options.createAgent, options);
+    return;
+  }
+  
+  // Handle global agent listing
+  if (options.listAgents) {
+    await listGlobalAgents(options);
+    return;
+  }
+  
+  // Handle global agent removal
+  if (options.removeAgent) {
+    await removeGlobalAgent(options.removeAgent, options);
+    return;
+  }
+  
+  // Handle global agent update
+  if (options.updateAgent) {
+    await updateGlobalAgent(options.updateAgent, options);
+    return;
+  }
+  
   // Handle command stats analysis (both singular and plural)
   if (options.commandStats || options.commandsStats) {
     await runCommandStats(options);

package/src/sdk/global-agent-manager.js

@@ -0,0 +1,626 @@
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const chalk = require('chalk');
+const ora = require('ora');
+
+// Global agents directory
+const GLOBAL_AGENTS_DIR = path.join(os.homedir(), '.claude-code-templates');
+const AGENTS_DIR = path.join(GLOBAL_AGENTS_DIR, 'agents');
+const LOCAL_BIN_DIR = path.join(GLOBAL_AGENTS_DIR, 'bin');
+
+// Try to use system bin directory for immediate availability
+const SYSTEM_BIN_DIR = '/usr/local/bin';
+const isSystemWritable = () => {
+  try {
+    const testFile = path.join(SYSTEM_BIN_DIR, '.test-write');
+    require('fs').writeFileSync(testFile, 'test', 'utf8');
+    require('fs').unlinkSync(testFile);
+    return true;
+  } catch (error) {
+    return false;
+  }
+};
+
+// Choose the best bin directory
+const BIN_DIR = isSystemWritable() ? SYSTEM_BIN_DIR : LOCAL_BIN_DIR;
+
+/**
+ * Create a global agent that can be executed from anywhere
+ */
+async function createGlobalAgent(agentName, options = {}) {
+  console.log(chalk.blue(`🤖 Creating global agent: ${agentName}`));
+  
+  try {
+    // Ensure directories exist
+    await fs.ensureDir(AGENTS_DIR);
+    await fs.ensureDir(LOCAL_BIN_DIR); // Always ensure local bin exists for backups
+    
+    if (BIN_DIR === SYSTEM_BIN_DIR) {
+      console.log(chalk.green('🌍 Installing to system directory (immediately available)'));
+    } else {
+      console.log(chalk.yellow('⚠️ Installing to user directory (requires PATH setup)'));
+      await fs.ensureDir(BIN_DIR);
+    }
+    
+    // Download agent from GitHub
+    const spinner = ora('Downloading agent from GitHub...').start();
+    
+    let githubUrl;
+    if (agentName.includes('/')) {
+      // Category/agent format
+      githubUrl = `https://raw.githubusercontent.com/davila7/claude-code-templates/main/cli-tool/components/agents/${agentName}.md`;
+    } else {
+      // Direct agent format - try to find it in any category
+      githubUrl = await findAgentUrl(agentName);
+      if (!githubUrl) {
+        spinner.fail(`Agent "${agentName}" not found`);
+        await showAvailableAgents();
+        return;
+      }
+    }
+    
+    const response = await fetch(githubUrl);
+    if (!response.ok) {
+      spinner.fail(`Failed to download agent: HTTP ${response.status}`);
+      if (response.status === 404) {
+        await showAvailableAgents();
+      }
+      return;
+    }
+    
+    const agentContent = await response.text();
+    spinner.succeed('Agent downloaded successfully');
+    
+    // Extract agent name for file/executable naming
+    const executableName = agentName.includes('/') ? 
+      agentName.split('/')[1] : agentName;
+    
+    // Save agent content
+    const agentFile = path.join(AGENTS_DIR, `${executableName}.md`);
+    await fs.writeFile(agentFile, agentContent, 'utf8');
+    
+    // Generate executable script
+    await generateExecutableScript(executableName, agentFile);
+    
+    console.log(chalk.green(`✅ Global agent '${executableName}' created successfully!`));
+    console.log(chalk.cyan('📦 Usage:'));
+    console.log(chalk.white(`  ${executableName} "your prompt here"`));
+    
+    if (BIN_DIR === SYSTEM_BIN_DIR) {
+      console.log(chalk.green('🎉 Ready to use immediately! No setup required.'));
+      console.log(chalk.gray('💡 Works in scripts, npm tasks, CI/CD, etc.'));
+    } else {
+      // Add to PATH (first time setup) only for user directory
+      await addToPath();
+      console.log(chalk.yellow('🔄 Restart your terminal or run:'));
+      console.log(chalk.gray('  source ~/.bashrc   # for bash'));
+      console.log(chalk.gray('  source ~/.zshrc    # for zsh'));
+    }
+    
+  } catch (error) {
+    console.log(chalk.red(`❌ Error creating global agent: ${error.message}`));
+  }
+}
+
+/**
+ * List installed global agents
+ */
+async function listGlobalAgents(options = {}) {
+  console.log(chalk.blue('📋 Installed Global Agents:'));
+  
+  try {
+    // Check both system and local bin directories
+    let systemAgents = [];
+    if (await fs.pathExists(SYSTEM_BIN_DIR)) {
+      const systemFiles = await fs.readdir(SYSTEM_BIN_DIR);
+      for (const file of systemFiles) {
+        if (!file.startsWith('.') && await fs.pathExists(path.join(AGENTS_DIR, `${file}.md`))) {
+          systemAgents.push(file);
+        }
+      }
+    }
+    
+    const localAgents = await fs.pathExists(LOCAL_BIN_DIR) ?
+      (await fs.readdir(LOCAL_BIN_DIR)).filter(file => !file.startsWith('.')) : [];
+    
+    const allAgents = [...new Set([...systemAgents, ...localAgents])];
+    
+    if (allAgents.length === 0) {
+      console.log(chalk.yellow('⚠️  No global agents installed yet.'));
+      console.log(chalk.gray('💡 Create one with: npx claude-code-templates@latest --create-agent <agent-name>'));
+      return;
+    }
+    
+    console.log(chalk.green(`\n✅ Found ${allAgents.length} global agent(s):\n`));
+    
+    for (const agent of allAgents) {
+      // Check which directory has the agent
+      const systemPath = path.join(SYSTEM_BIN_DIR, agent);
+      const localPath = path.join(LOCAL_BIN_DIR, agent);
+      
+      let agentPath, location;
+      if (await fs.pathExists(systemPath)) {
+        agentPath = systemPath;
+        location = '🌍 system';
+      } else {
+        agentPath = localPath;
+        location = '👤 user';
+      }
+      
+      const stats = await fs.stat(agentPath);
+      const isExecutable = (stats.mode & parseInt('111', 8)) !== 0;
+      
+      console.log(chalk.cyan(`  ${isExecutable ? '✅' : '❌'} ${agent} (${location})`));
+      console.log(chalk.gray(`      Usage: ${agent} "your prompt"`));
+      console.log(chalk.gray(`      Created: ${stats.birthtime.toLocaleDateString()}`));
+      console.log('');
+    }
+    
+    console.log(chalk.blue('🌟 Global Usage:'));
+    console.log(chalk.gray('  • Run from any directory: <agent-name> "prompt"'));
+    console.log(chalk.gray('  • List agents: npx claude-code-templates@latest --list-agents'));
+    console.log(chalk.gray('  • Remove agent: npx claude-code-templates@latest --remove-agent <name>'));
+    
+  } catch (error) {
+    console.log(chalk.red(`❌ Error listing agents: ${error.message}`));
+  }
+}
+
+/**
+ * Remove a global agent
+ */
+async function removeGlobalAgent(agentName, options = {}) {
+  console.log(chalk.blue(`🗑️  Removing global agent: ${agentName}`));
+  
+  try {
+    const systemExecutablePath = path.join(SYSTEM_BIN_DIR, agentName);
+    const localExecutablePath = path.join(LOCAL_BIN_DIR, agentName);
+    const agentPath = path.join(AGENTS_DIR, `${agentName}.md`);
+    
+    let removed = false;
+    
+    // Remove from system directory
+    if (await fs.pathExists(systemExecutablePath)) {
+      await fs.remove(systemExecutablePath);
+      console.log(chalk.green(`✅ Removed system executable: ${agentName}`));
+      removed = true;
+    }
+    
+    // Remove from local directory
+    if (await fs.pathExists(localExecutablePath)) {
+      await fs.remove(localExecutablePath);
+      console.log(chalk.green(`✅ Removed local executable: ${agentName}`));
+      removed = true;
+    }
+    
+    // Remove agent file
+    if (await fs.pathExists(agentPath)) {
+      await fs.remove(agentPath);
+      console.log(chalk.green(`✅ Removed agent file: ${agentName}.md`));
+      removed = true;
+    }
+    
+    if (!removed) {
+      console.log(chalk.yellow(`⚠️  Agent '${agentName}' not found.`));
+      console.log(chalk.gray('💡 List available agents with: --list-agents'));
+      return;
+    }
+    
+    console.log(chalk.green(`🎉 Global agent '${agentName}' removed successfully!`));
+    
+  } catch (error) {
+    console.log(chalk.red(`❌ Error removing agent: ${error.message}`));
+  }
+}
+
+/**
+ * Update a global agent
+ */
+async function updateGlobalAgent(agentName, options = {}) {
+  console.log(chalk.blue(`🔄 Updating global agent: ${agentName}`));
+  
+  try {
+    const executablePath = path.join(BIN_DIR, agentName);
+    
+    if (!await fs.pathExists(executablePath)) {
+      console.log(chalk.yellow(`⚠️  Agent '${agentName}' not found.`));
+      console.log(chalk.gray('💡 Create it with: --create-agent <agent-name>'));
+      return;
+    }
+    
+    // Re-download and recreate
+    console.log(chalk.gray('🔄 Re-downloading latest version...'));
+    await createGlobalAgent(agentName, { ...options, update: true });
+    
+  } catch (error) {
+    console.log(chalk.red(`❌ Error updating agent: ${error.message}`));
+  }
+}
+
+/**
+ * Generate executable script for an agent
+ */
+async function generateExecutableScript(agentName, agentFile) {
+  const scriptContent = `#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Check if Claude CLI is available
+function checkClaudeCLI() {
+  try {
+    execSync('claude --version', { stdio: 'ignore' });
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+// Read agent system prompt
+const agentPath = '${agentFile}';
+if (!fs.existsSync(agentPath)) {
+  console.error('❌ Agent file not found:', agentPath);
+  process.exit(1);
+}
+
+const systemPrompt = fs.readFileSync(agentPath, 'utf8');
+
+// Parse arguments and detect context
+const args = process.argv.slice(2);
+let userInput = '';
+let explicitFiles = [];
+let explicitDirs = [];
+let autoDetect = true;
+
+// Parse command line arguments
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  
+  if (arg === '--file' && i + 1 < args.length) {
+    explicitFiles.push(args[++i]);
+    autoDetect = false; // Disable auto-detect when explicit files provided
+  } else if (arg === '--dir' && i + 1 < args.length) {
+    explicitDirs.push(args[++i]);
+    autoDetect = false;
+  } else if (arg === '--no-auto') {
+    autoDetect = false;
+  } else if (arg === '--help' || arg === '-h') {
+    console.log('Usage: ${agentName} [options] "your prompt"');
+    console.log('');
+    console.log('Context Options:');
+    console.log('  [default]           Auto-detect project files (smart context)');
+    console.log('  --file <path>       Include specific file');
+    console.log('  --dir <path>        Include specific directory');
+    console.log('  --no-auto           Disable auto-detection');
+    console.log('');
+    console.log('Examples:');
+    console.log('  ${agentName} "review for security issues"        # Auto-detect');
+    console.log('  ${agentName} --file auth.js "check this file"    # Specific file');
+    console.log('  ${agentName} --no-auto "general advice"          # No context');
+    process.exit(0);
+  } else if (!arg.startsWith('--')) {
+    userInput += arg + ' ';
+  }
+}
+
+userInput = userInput.trim();
+
+if (!userInput) {
+  console.error('❌ Please provide a prompt');
+  console.error('Usage: ${agentName} [options] "your prompt"');
+  process.exit(1);
+}
+
+// Auto-detect project context if enabled
+let contextPrompt = '';
+if (autoDetect && explicitFiles.length === 0 && explicitDirs.length === 0) {
+  const fs = require('fs');
+  const path = require('path');
+  const cwd = process.cwd();
+  
+  // Detect project type and relevant files
+  let projectType = 'unknown';
+  let relevantFiles = [];
+  
+  // Check for common project indicators
+  if (fs.existsSync('package.json')) {
+    projectType = 'javascript/node';
+    const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+    
+    // Add framework detection
+    if (packageJson.dependencies?.react || packageJson.devDependencies?.react) {
+      projectType = 'react';
+    } else if (packageJson.dependencies?.vue || packageJson.devDependencies?.vue) {
+      projectType = 'vue';
+    } else if (packageJson.dependencies?.next || packageJson.devDependencies?.next) {
+      projectType = 'nextjs';
+    }
+    
+    // Common files to include for JS projects
+    const jsFiles = ['src/', 'lib/', 'components/', 'pages/', 'api/', 'routes/'];
+    jsFiles.forEach(dir => {
+      if (fs.existsSync(dir)) relevantFiles.push(dir);
+    });
+    
+  } else if (fs.existsSync('requirements.txt') || fs.existsSync('pyproject.toml')) {
+    projectType = 'python';
+    relevantFiles = ['*.py', 'src/', 'app/', 'api/'];
+    
+  } else if (fs.existsSync('Cargo.toml')) {
+    projectType = 'rust';
+    relevantFiles = ['src/', 'Cargo.toml'];
+    
+  } else if (fs.existsSync('go.mod')) {
+    projectType = 'go';
+    relevantFiles = ['*.go', 'cmd/', 'internal/', 'pkg/'];
+  }
+  
+  // Build context prompt
+  if (projectType !== 'unknown') {
+    contextPrompt = \`
+
+📁 PROJECT CONTEXT:
+- Project type: \${projectType}
+- Working directory: \${path.basename(cwd)}
+- Auto-detected relevant files/folders: \${relevantFiles.join(', ')}
+
+Please analyze the \${userInput} in the context of this \${projectType} project. You have access to read any files in the current directory using the Read tool.\`;
+  }
+}
+
+// Check Claude CLI availability
+if (!checkClaudeCLI()) {
+  console.error('❌ Claude CLI not found in PATH');
+  console.error('💡 Install Claude CLI: https://claude.ai/code');
+  console.error('💡 Or install via npm: npm install -g @anthropic-ai/claude-code');
+  process.exit(1);
+}
+
+// Escape quotes in system prompt for shell execution
+const escapedSystemPrompt = systemPrompt.replace(/"/g, '\\\\"').replace(/\`/g, '\\\\\`');
+
+// Build final prompt with context
+const finalPrompt = userInput + contextPrompt;
+const escapedFinalPrompt = finalPrompt.replace(/"/g, '\\\\"').replace(/\`/g, '\\\\\`');
+
+// Build Claude command with SDK
+const claudeCmd = \`claude -p "\${escapedFinalPrompt}" --append-system-prompt "\${escapedSystemPrompt}"\`;
+
+// Show loading indicator
+const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+let currentFrame = 0;
+const agentDisplayName = '${agentName}'.replace(/-/g, ' ').replace(/\\b\\w/g, l => l.toUpperCase());
+
+console.error(\`\\n🤖 \${agentDisplayName} is thinking...\`);
+const loader = setInterval(() => {
+  process.stderr.write(\`\\r\${frames[currentFrame]} Claude Code is working... \`);
+  currentFrame = (currentFrame + 1) % frames.length;
+}, 100);
+
+try {
+  // Execute Claude with the agent's system prompt
+  execSync(claudeCmd, { 
+    stdio: ['inherit', 'inherit', 'pipe'],
+    cwd: process.cwd() 
+  });
+  
+  // Clear loader
+  clearInterval(loader);
+  process.stderr.write('\\r✅ Response ready!\\n\\n');
+  
+} catch (error) {
+  clearInterval(loader);
+  process.stderr.write('\\r');
+  console.error('❌ Error executing Claude:', error.message);
+  process.exit(1);
+}
+`;
+
+  const scriptPath = path.join(BIN_DIR, agentName);
+  await fs.writeFile(scriptPath, scriptContent, 'utf8');
+  
+  // Make executable (Unix/Linux/macOS)
+  if (process.platform !== 'win32') {
+    await fs.chmod(scriptPath, 0o755);
+  }
+}
+
+/**
+ * Add global agents bin directory to PATH
+ */
+async function addToPath() {
+  const shell = process.env.SHELL || '';
+  const isWindows = process.platform === 'win32';
+  
+  if (isWindows) {
+    // Windows PATH management
+    console.log(chalk.yellow('🪟 Windows detected:'));
+    console.log(chalk.gray(`Add this to your PATH: ${BIN_DIR}`));
+    console.log(chalk.gray('Or run this in PowerShell as Administrator:'));
+    console.log(chalk.white(`[Environment]::SetEnvironmentVariable("Path", $env:Path + ";${BIN_DIR}", "User")`));
+    return;
+  }
+  
+  // Unix-like systems
+  const pathExport = `export PATH="${BIN_DIR}:$PATH"`;
+  
+  // Determine shell config files to update
+  const configFiles = [];
+  
+  if (shell.includes('bash') || !shell) {
+    configFiles.push(path.join(os.homedir(), '.bashrc'));
+    configFiles.push(path.join(os.homedir(), '.bash_profile'));
+  }
+  
+  if (shell.includes('zsh')) {
+    configFiles.push(path.join(os.homedir(), '.zshrc'));
+  }
+  
+  if (shell.includes('fish')) {
+    const fishConfigDir = path.join(os.homedir(), '.config', 'fish');
+    await fs.ensureDir(fishConfigDir);
+    configFiles.push(path.join(fishConfigDir, 'config.fish'));
+  }
+  
+  // Add default files if shell not detected
+  if (configFiles.length === 0) {
+    configFiles.push(path.join(os.homedir(), '.bashrc'));
+    configFiles.push(path.join(os.homedir(), '.zshrc'));
+  }
+  
+  // Check if PATH is already added
+  let alreadyInPath = false;
+  
+  for (const configFile of configFiles) {
+    if (await fs.pathExists(configFile)) {
+      const content = await fs.readFile(configFile, 'utf8');
+      if (content.includes(BIN_DIR)) {
+        alreadyInPath = true;
+        break;
+      }
+    }
+  }
+  
+  if (alreadyInPath) {
+    console.log(chalk.green('✅ PATH already configured'));
+    return;
+  }
+  
+  // Add to PATH in config files
+  console.log(chalk.blue('🔧 Adding to PATH...'));
+  
+  for (const configFile of configFiles) {
+    try {
+      let content = '';
+      if (await fs.pathExists(configFile)) {
+        content = await fs.readFile(configFile, 'utf8');
+      }
+      
+      // Add PATH export if not already present
+      if (!content.includes(BIN_DIR)) {
+        const newContent = content + `\n# Claude Code Templates - Global Agents\n${pathExport}\n`;
+        await fs.writeFile(configFile, newContent, 'utf8');
+        console.log(chalk.green(`✅ Updated ${path.basename(configFile)}`));
+      }
+    } catch (error) {
+      console.log(chalk.yellow(`⚠️  Could not update ${configFile}: ${error.message}`));
+    }
+  }
+}
+
+/**
+ * Find agent URL by searching in all categories
+ */
+async function findAgentUrl(agentName) {
+  try {
+    // First try root level
+    const rootUrl = `https://raw.githubusercontent.com/davila7/claude-code-templates/main/cli-tool/components/agents/${agentName}.md`;
+    const rootResponse = await fetch(rootUrl);
+    if (rootResponse.ok) {
+      return rootUrl;
+    }
+    
+    // Search in categories
+    const categoriesResponse = await fetch('https://api.github.com/repos/davila7/claude-code-templates/contents/cli-tool/components/agents');
+    if (!categoriesResponse.ok) {
+      return null;
+    }
+    
+    const contents = await categoriesResponse.json();
+    
+    for (const item of contents) {
+      if (item.type === 'dir') {
+        const categoryUrl = `https://raw.githubusercontent.com/davila7/claude-code-templates/main/cli-tool/components/agents/${item.name}/${agentName}.md`;
+        try {
+          const categoryResponse = await fetch(categoryUrl);
+          if (categoryResponse.ok) {
+            return categoryUrl;
+          }
+        } catch (error) {
+          // Continue searching
+        }
+      }
+    }
+    
+    return null;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Show available agents for user selection
+ */
+async function showAvailableAgents() {
+  console.log(chalk.yellow('\n📋 Available Agents:'));
+  console.log(chalk.gray('Use format: category/agent-name or just agent-name\n'));
+  
+  try {
+    const response = await fetch('https://api.github.com/repos/davila7/claude-code-templates/contents/cli-tool/components/agents');
+    if (!response.ok) {
+      console.log(chalk.red('❌ Could not fetch available agents from GitHub'));
+      return;
+    }
+    
+    const contents = await response.json();
+    const agents = [];
+    
+    for (const item of contents) {
+      if (item.type === 'file' && item.name.endsWith('.md')) {
+        agents.push({ name: item.name.replace('.md', ''), category: 'root' });
+      } else if (item.type === 'dir') {
+        try {
+          const categoryResponse = await fetch(`https://api.github.com/repos/davila7/claude-code-templates/contents/cli-tool/components/agents/${item.name}`);
+          if (categoryResponse.ok) {
+            const categoryContents = await categoryResponse.json();
+            for (const categoryItem of categoryContents) {
+              if (categoryItem.type === 'file' && categoryItem.name.endsWith('.md')) {
+                agents.push({
+                  name: categoryItem.name.replace('.md', ''),
+                  category: item.name,
+                  path: `${item.name}/${categoryItem.name.replace('.md', '')}`
+                });
+              }
+            }
+          }
+        } catch (error) {
+          // Skip category on error
+        }
+      }
+    }
+    
+    // Group by category
+    const grouped = agents.reduce((acc, agent) => {
+      const category = agent.category === 'root' ? '🤖 General' : `📁 ${agent.category}`;
+      if (!acc[category]) acc[category] = [];
+      acc[category].push(agent);
+      return acc;
+    }, {});
+    
+    Object.entries(grouped).forEach(([category, categoryAgents]) => {
+      console.log(chalk.cyan(category));
+      categoryAgents.forEach(agent => {
+        const displayName = agent.path || agent.name;
+        console.log(chalk.gray(`  • ${displayName}`));
+      });
+      console.log('');
+    });
+    
+    console.log(chalk.blue('Examples:'));
+    console.log(chalk.gray('  npx claude-code-templates@latest --create-agent api-security-audit'));
+    console.log(chalk.gray('  npx claude-code-templates@latest --create-agent deep-research-team/academic-researcher'));
+    
+  } catch (error) {
+    console.log(chalk.red('❌ Error fetching agents:', error.message));
+  }
+}
+
+module.exports = {
+  createGlobalAgent,
+  listGlobalAgents,
+  removeGlobalAgent,
+  updateGlobalAgent,
+  showAvailableAgents
+};